hledger 1.29 → 1.29.1
raw patch · 18 files changed
+22013/−21983 lines, 18 filesdep ~basedep ~hledger-libPVP: major bump suggested
API removals or changes: PVP suggests a major version bump
Dependency ranges changed: base, hledger-lib
API changes (from Hackage documentation)
+ Hledger.Cli.Script: ($>) :: Functor f => f a -> b -> f b
+ Hledger.Cli.Script: (*>) :: Applicative f => f a -> f b -> f b
+ Hledger.Cli.Script: (<$>) :: Functor f => (a -> b) -> f a -> f b
+ Hledger.Cli.Script: (<&>) :: Functor f => f a -> (a -> b) -> f b
+ Hledger.Cli.Script: (<*) :: Applicative f => f a -> f b -> f a
+ Hledger.Cli.Script: (<**>) :: Applicative f => f a -> f (a -> b) -> f b
+ Hledger.Cli.Script: (<*>) :: Applicative f => f (a -> b) -> f a -> f b
+ Hledger.Cli.Script: (<|>) :: Alternative f => f a -> f a -> f a
+ Hledger.Cli.Script: AbsoluteSeek :: SeekMode
+ Hledger.Cli.Script: AppendMode :: IOMode
+ Hledger.Cli.Script: BlockBuffering :: Maybe Int -> BufferMode
+ Hledger.Cli.Script: CRLF :: Newline
+ Hledger.Cli.Script: ClosePunctuation :: GeneralCategory
+ Hledger.Cli.Script: ConnectorPunctuation :: GeneralCategory
+ Hledger.Cli.Script: Const :: a -> Const a (b :: k)
+ Hledger.Cli.Script: Control :: GeneralCategory
+ Hledger.Cli.Script: CurrencySymbol :: GeneralCategory
+ Hledger.Cli.Script: DashPunctuation :: GeneralCategory
+ Hledger.Cli.Script: DecimalNumber :: GeneralCategory
+ Hledger.Cli.Script: EnclosingMark :: GeneralCategory
+ Hledger.Cli.Script: FinalQuote :: GeneralCategory
+ Hledger.Cli.Script: Format :: GeneralCategory
+ Hledger.Cli.Script: InitialQuote :: GeneralCategory
+ Hledger.Cli.Script: LF :: Newline
+ Hledger.Cli.Script: LetterNumber :: GeneralCategory
+ Hledger.Cli.Script: LineBuffering :: BufferMode
+ Hledger.Cli.Script: LineSeparator :: GeneralCategory
+ Hledger.Cli.Script: LowercaseLetter :: GeneralCategory
+ Hledger.Cli.Script: MathSymbol :: GeneralCategory
+ Hledger.Cli.Script: ModifierLetter :: GeneralCategory
+ Hledger.Cli.Script: ModifierSymbol :: GeneralCategory
+ Hledger.Cli.Script: NewlineMode :: Newline -> Newline -> NewlineMode
+ Hledger.Cli.Script: NoBuffering :: BufferMode
+ Hledger.Cli.Script: NonSpacingMark :: GeneralCategory
+ Hledger.Cli.Script: NotAssigned :: GeneralCategory
+ Hledger.Cli.Script: OpenPunctuation :: GeneralCategory
+ Hledger.Cli.Script: OtherLetter :: GeneralCategory
+ Hledger.Cli.Script: OtherNumber :: GeneralCategory
+ Hledger.Cli.Script: OtherPunctuation :: GeneralCategory
+ Hledger.Cli.Script: OtherSymbol :: GeneralCategory
+ Hledger.Cli.Script: ParagraphSeparator :: GeneralCategory
+ Hledger.Cli.Script: PrivateUse :: GeneralCategory
+ Hledger.Cli.Script: ReadMode :: IOMode
+ Hledger.Cli.Script: ReadWriteMode :: IOMode
+ Hledger.Cli.Script: RelativeSeek :: SeekMode
+ Hledger.Cli.Script: SeekFromEnd :: SeekMode
+ Hledger.Cli.Script: Space :: GeneralCategory
+ Hledger.Cli.Script: SpacingCombiningMark :: GeneralCategory
+ Hledger.Cli.Script: Surrogate :: GeneralCategory
+ Hledger.Cli.Script: TitlecaseLetter :: GeneralCategory
+ Hledger.Cli.Script: UppercaseLetter :: GeneralCategory
+ Hledger.Cli.Script: WrapArrow :: a b c -> WrappedArrow (a :: Type -> Type -> Type) b c
+ Hledger.Cli.Script: WrapMonad :: m a -> WrappedMonad (m :: Type -> Type) a
+ Hledger.Cli.Script: WriteMode :: IOMode
+ Hledger.Cli.Script: ZipList :: [a] -> ZipList a
+ Hledger.Cli.Script: [getConst] :: Const a (b :: k) -> a
+ Hledger.Cli.Script: [getZipList] :: ZipList a -> [a]
+ Hledger.Cli.Script: [inputNL] :: NewlineMode -> Newline
+ Hledger.Cli.Script: [outputNL] :: NewlineMode -> Newline
+ Hledger.Cli.Script: [unwrapArrow] :: WrappedArrow (a :: Type -> Type -> Type) b c -> a b c
+ Hledger.Cli.Script: [unwrapMonad] :: WrappedMonad (m :: Type -> Type) a -> m a
+ Hledger.Cli.Script: addMVarFinalizer :: MVar a -> IO () -> IO ()
+ Hledger.Cli.Script: alreadyExistsErrorType :: IOErrorType
+ Hledger.Cli.Script: alreadyInUseErrorType :: IOErrorType
+ Hledger.Cli.Script: annotateIOError :: IOError -> String -> Maybe Handle -> Maybe FilePath -> IOError
+ Hledger.Cli.Script: appendFile :: FilePath -> String -> IO ()
+ Hledger.Cli.Script: asum :: (Foldable t, Alternative f) => t (f a) -> f a
+ Hledger.Cli.Script: catchIOError :: IO a -> (IOError -> IO a) -> IO a
+ Hledger.Cli.Script: char8 :: TextEncoding
+ Hledger.Cli.Script: chr :: Int -> Char
+ Hledger.Cli.Script: class Applicative f => Alternative (f :: Type -> Type)
+ Hledger.Cli.Script: class Functor f => Applicative (f :: Type -> Type)
+ Hledger.Cli.Script: data BufferMode
+ Hledger.Cli.Script: data Chan a
+ Hledger.Cli.Script: data Char
+ Hledger.Cli.Script: data GeneralCategory
+ Hledger.Cli.Script: data Handle
+ Hledger.Cli.Script: data HandlePosn
+ Hledger.Cli.Script: data IO a
+ Hledger.Cli.Script: data IOErrorType
+ Hledger.Cli.Script: data IOMode
+ Hledger.Cli.Script: data MVar a
+ Hledger.Cli.Script: data Newline
+ Hledger.Cli.Script: data NewlineMode
+ Hledger.Cli.Script: data QSem
+ Hledger.Cli.Script: data QSemN
+ Hledger.Cli.Script: data SeekMode
+ Hledger.Cli.Script: data TextEncoding
+ Hledger.Cli.Script: data ThreadId
+ Hledger.Cli.Script: digitToInt :: Char -> Int
+ Hledger.Cli.Script: doesNotExistErrorType :: IOErrorType
+ Hledger.Cli.Script: dupChan :: Chan a -> IO (Chan a)
+ Hledger.Cli.Script: empty :: Alternative f => f a
+ Hledger.Cli.Script: eofErrorType :: IOErrorType
+ Hledger.Cli.Script: fixIO :: (a -> IO a) -> IO a
+ Hledger.Cli.Script: forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId
+ Hledger.Cli.Script: forkIO :: IO () -> IO ThreadId
+ Hledger.Cli.Script: forkIOWithUnmask :: ((forall a. () => IO a -> IO a) -> IO ()) -> IO ThreadId
+ Hledger.Cli.Script: forkOS :: IO () -> IO ThreadId
+ Hledger.Cli.Script: forkOSWithUnmask :: ((forall a. () => IO a -> IO a) -> IO ()) -> IO ThreadId
+ Hledger.Cli.Script: forkOn :: Int -> IO () -> IO ThreadId
+ Hledger.Cli.Script: forkOnWithUnmask :: Int -> ((forall a. () => IO a -> IO a) -> IO ()) -> IO ThreadId
+ Hledger.Cli.Script: fullErrorType :: IOErrorType
+ Hledger.Cli.Script: generalCategory :: Char -> GeneralCategory
+ Hledger.Cli.Script: getChanContents :: Chan a -> IO [a]
+ Hledger.Cli.Script: getChar :: IO Char
+ Hledger.Cli.Script: getContents :: IO String
+ Hledger.Cli.Script: getContents' :: IO String
+ Hledger.Cli.Script: getLine :: IO String
+ Hledger.Cli.Script: getNumCapabilities :: IO Int
+ Hledger.Cli.Script: hClose :: Handle -> IO ()
+ Hledger.Cli.Script: hFileSize :: Handle -> IO Integer
+ Hledger.Cli.Script: hFlush :: Handle -> IO ()
+ Hledger.Cli.Script: hGetBuf :: Handle -> Ptr a -> Int -> IO Int
+ Hledger.Cli.Script: hGetBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int
+ Hledger.Cli.Script: hGetBufSome :: Handle -> Ptr a -> Int -> IO Int
+ Hledger.Cli.Script: hGetBuffering :: Handle -> IO BufferMode
+ Hledger.Cli.Script: hGetChar :: Handle -> IO Char
+ Hledger.Cli.Script: hGetContents :: Handle -> IO String
+ Hledger.Cli.Script: hGetContents' :: Handle -> IO String
+ Hledger.Cli.Script: hGetEcho :: Handle -> IO Bool
+ Hledger.Cli.Script: hGetEncoding :: Handle -> IO (Maybe TextEncoding)
+ Hledger.Cli.Script: hGetLine :: Handle -> IO String
+ Hledger.Cli.Script: hGetPosn :: Handle -> IO HandlePosn
+ Hledger.Cli.Script: hIsClosed :: Handle -> IO Bool
+ Hledger.Cli.Script: hIsEOF :: Handle -> IO Bool
+ Hledger.Cli.Script: hIsOpen :: Handle -> IO Bool
+ Hledger.Cli.Script: hIsReadable :: Handle -> IO Bool
+ Hledger.Cli.Script: hIsSeekable :: Handle -> IO Bool
+ Hledger.Cli.Script: hIsTerminalDevice :: Handle -> IO Bool
+ Hledger.Cli.Script: hIsWritable :: Handle -> IO Bool
+ Hledger.Cli.Script: hLookAhead :: Handle -> IO Char
+ Hledger.Cli.Script: hPrint :: Show a => Handle -> a -> IO ()
+ Hledger.Cli.Script: hPutBuf :: Handle -> Ptr a -> Int -> IO ()
+ Hledger.Cli.Script: hPutBufNonBlocking :: Handle -> Ptr a -> Int -> IO Int
+ Hledger.Cli.Script: hPutChar :: Handle -> Char -> IO ()
+ Hledger.Cli.Script: hPutStr :: Handle -> String -> IO ()
+ Hledger.Cli.Script: hPutStrLn :: Handle -> String -> IO ()
+ Hledger.Cli.Script: hReady :: Handle -> IO Bool
+ Hledger.Cli.Script: hSeek :: Handle -> SeekMode -> Integer -> IO ()
+ Hledger.Cli.Script: hSetBinaryMode :: Handle -> Bool -> IO ()
+ Hledger.Cli.Script: hSetBuffering :: Handle -> BufferMode -> IO ()
+ Hledger.Cli.Script: hSetEcho :: Handle -> Bool -> IO ()
+ Hledger.Cli.Script: hSetEncoding :: Handle -> TextEncoding -> IO ()
+ Hledger.Cli.Script: hSetFileSize :: Handle -> Integer -> IO ()
+ Hledger.Cli.Script: hSetNewlineMode :: Handle -> NewlineMode -> IO ()
+ Hledger.Cli.Script: hSetPosn :: HandlePosn -> IO ()
+ Hledger.Cli.Script: hShow :: Handle -> IO String
+ Hledger.Cli.Script: hTell :: Handle -> IO Integer
+ Hledger.Cli.Script: hWaitForInput :: Handle -> Int -> IO Bool
+ Hledger.Cli.Script: illegalOperationErrorType :: IOErrorType
+ Hledger.Cli.Script: infixl 3 <|>
+ Hledger.Cli.Script: intToDigit :: Int -> Char
+ Hledger.Cli.Script: interact :: (String -> String) -> IO ()
+ Hledger.Cli.Script: ioError :: IOError -> IO a
+ Hledger.Cli.Script: ioeGetErrorString :: IOError -> String
+ Hledger.Cli.Script: ioeGetErrorType :: IOError -> IOErrorType
+ Hledger.Cli.Script: ioeGetFileName :: IOError -> Maybe FilePath
+ Hledger.Cli.Script: ioeGetHandle :: IOError -> Maybe Handle
+ Hledger.Cli.Script: ioeGetLocation :: IOError -> String
+ Hledger.Cli.Script: ioeSetErrorString :: IOError -> String -> IOError
+ Hledger.Cli.Script: ioeSetErrorType :: IOError -> IOErrorType -> IOError
+ Hledger.Cli.Script: ioeSetFileName :: IOError -> FilePath -> IOError
+ Hledger.Cli.Script: ioeSetHandle :: IOError -> Handle -> IOError
+ Hledger.Cli.Script: ioeSetLocation :: IOError -> String -> IOError
+ Hledger.Cli.Script: isAlpha :: Char -> Bool
+ Hledger.Cli.Script: isAlphaNum :: Char -> Bool
+ Hledger.Cli.Script: isAlreadyExistsError :: IOError -> Bool
+ Hledger.Cli.Script: isAlreadyExistsErrorType :: IOErrorType -> Bool
+ Hledger.Cli.Script: isAlreadyInUseError :: IOError -> Bool
+ Hledger.Cli.Script: isAlreadyInUseErrorType :: IOErrorType -> Bool
+ Hledger.Cli.Script: isAscii :: Char -> Bool
+ Hledger.Cli.Script: isAsciiLower :: Char -> Bool
+ Hledger.Cli.Script: isAsciiUpper :: Char -> Bool
+ Hledger.Cli.Script: isControl :: Char -> Bool
+ Hledger.Cli.Script: isCurrentThreadBound :: IO Bool
+ Hledger.Cli.Script: isDigit :: Char -> Bool
+ Hledger.Cli.Script: isDoesNotExistError :: IOError -> Bool
+ Hledger.Cli.Script: isDoesNotExistErrorType :: IOErrorType -> Bool
+ Hledger.Cli.Script: isEOF :: IO Bool
+ Hledger.Cli.Script: isEOFError :: IOError -> Bool
+ Hledger.Cli.Script: isEOFErrorType :: IOErrorType -> Bool
+ Hledger.Cli.Script: isEmptyMVar :: MVar a -> IO Bool
+ Hledger.Cli.Script: isFullError :: IOError -> Bool
+ Hledger.Cli.Script: isFullErrorType :: IOErrorType -> Bool
+ Hledger.Cli.Script: isHexDigit :: Char -> Bool
+ Hledger.Cli.Script: isIllegalOperation :: IOError -> Bool
+ Hledger.Cli.Script: isIllegalOperationErrorType :: IOErrorType -> Bool
+ Hledger.Cli.Script: isLatin1 :: Char -> Bool
+ Hledger.Cli.Script: isLetter :: Char -> Bool
+ Hledger.Cli.Script: isLower :: Char -> Bool
+ Hledger.Cli.Script: isMark :: Char -> Bool
+ Hledger.Cli.Script: isNumber :: Char -> Bool
+ Hledger.Cli.Script: isOctDigit :: Char -> Bool
+ Hledger.Cli.Script: isPermissionError :: IOError -> Bool
+ Hledger.Cli.Script: isPermissionErrorType :: IOErrorType -> Bool
+ Hledger.Cli.Script: isPrint :: Char -> Bool
+ Hledger.Cli.Script: isPunctuation :: Char -> Bool
+ Hledger.Cli.Script: isResourceVanishedError :: IOError -> Bool
+ Hledger.Cli.Script: isResourceVanishedErrorType :: IOErrorType -> Bool
+ Hledger.Cli.Script: isSeparator :: Char -> Bool
+ Hledger.Cli.Script: isSpace :: Char -> Bool
+ Hledger.Cli.Script: isSymbol :: Char -> Bool
+ Hledger.Cli.Script: isUpper :: Char -> Bool
+ Hledger.Cli.Script: isUserError :: IOError -> Bool
+ Hledger.Cli.Script: isUserErrorType :: IOErrorType -> Bool
+ Hledger.Cli.Script: killThread :: ThreadId -> IO ()
+ Hledger.Cli.Script: latin1 :: TextEncoding
+ Hledger.Cli.Script: lexLitChar :: ReadS String
+ Hledger.Cli.Script: liftA :: Applicative f => (a -> b) -> f a -> f b
+ Hledger.Cli.Script: liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c
+ Hledger.Cli.Script: liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
+ Hledger.Cli.Script: localeEncoding :: TextEncoding
+ Hledger.Cli.Script: many :: Alternative f => f a -> f [a]
+ Hledger.Cli.Script: mkIOError :: IOErrorType -> String -> Maybe Handle -> Maybe FilePath -> IOError
+ Hledger.Cli.Script: mkTextEncoding :: String -> IO TextEncoding
+ Hledger.Cli.Script: mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a))
+ Hledger.Cli.Script: mkWeakThreadId :: ThreadId -> IO (Weak ThreadId)
+ Hledger.Cli.Script: modifyIOError :: (IOError -> IOError) -> IO a -> IO a
+ Hledger.Cli.Script: modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO b
+ Hledger.Cli.Script: modifyMVarMasked :: MVar a -> (a -> IO (a, b)) -> IO b
+ Hledger.Cli.Script: modifyMVarMasked_ :: MVar a -> (a -> IO a) -> IO ()
+ Hledger.Cli.Script: modifyMVar_ :: MVar a -> (a -> IO a) -> IO ()
+ Hledger.Cli.Script: myThreadId :: IO ThreadId
+ Hledger.Cli.Script: nativeNewline :: Newline
+ Hledger.Cli.Script: nativeNewlineMode :: NewlineMode
+ Hledger.Cli.Script: newChan :: IO (Chan a)
+ Hledger.Cli.Script: newEmptyMVar :: IO (MVar a)
+ Hledger.Cli.Script: newMVar :: a -> IO (MVar a)
+ Hledger.Cli.Script: newQSem :: Int -> IO QSem
+ Hledger.Cli.Script: newQSemN :: Int -> IO QSemN
+ Hledger.Cli.Script: newtype Const a (b :: k)
+ Hledger.Cli.Script: newtype WrappedArrow (a :: Type -> Type -> Type) b c
+ Hledger.Cli.Script: newtype WrappedMonad (m :: Type -> Type) a
+ Hledger.Cli.Script: newtype ZipList a
+ Hledger.Cli.Script: noNewlineTranslation :: NewlineMode
+ Hledger.Cli.Script: openBinaryFile :: FilePath -> IOMode -> IO Handle
+ Hledger.Cli.Script: openBinaryTempFile :: FilePath -> String -> IO (FilePath, Handle)
+ Hledger.Cli.Script: openBinaryTempFileWithDefaultPermissions :: FilePath -> String -> IO (FilePath, Handle)
+ Hledger.Cli.Script: openFile :: FilePath -> IOMode -> IO Handle
+ Hledger.Cli.Script: openTempFile :: FilePath -> String -> IO (FilePath, Handle)
+ Hledger.Cli.Script: openTempFileWithDefaultPermissions :: FilePath -> String -> IO (FilePath, Handle)
+ Hledger.Cli.Script: optional :: Alternative f => f a -> f (Maybe a)
+ Hledger.Cli.Script: ord :: Char -> Int
+ Hledger.Cli.Script: permissionErrorType :: IOErrorType
+ Hledger.Cli.Script: print :: Show a => a -> IO ()
+ Hledger.Cli.Script: pure :: Applicative f => a -> f a
+ Hledger.Cli.Script: putChar :: Char -> IO ()
+ Hledger.Cli.Script: putMVar :: MVar a -> a -> IO ()
+ Hledger.Cli.Script: putStr :: String -> IO ()
+ Hledger.Cli.Script: putStrLn :: String -> IO ()
+ Hledger.Cli.Script: readChan :: Chan a -> IO a
+ Hledger.Cli.Script: readFile :: FilePath -> IO String
+ Hledger.Cli.Script: readFile' :: FilePath -> IO String
+ Hledger.Cli.Script: readIO :: Read a => String -> IO a
+ Hledger.Cli.Script: readLitChar :: ReadS Char
+ Hledger.Cli.Script: readLn :: Read a => IO a
+ Hledger.Cli.Script: readMVar :: MVar a -> IO a
+ Hledger.Cli.Script: resourceVanishedErrorType :: IOErrorType
+ Hledger.Cli.Script: rtsSupportsBoundThreads :: Bool
+ Hledger.Cli.Script: runInBoundThread :: IO a -> IO a
+ Hledger.Cli.Script: runInUnboundThread :: IO a -> IO a
+ Hledger.Cli.Script: setNumCapabilities :: Int -> IO ()
+ Hledger.Cli.Script: showLitChar :: Char -> ShowS
+ Hledger.Cli.Script: signalQSem :: QSem -> IO ()
+ Hledger.Cli.Script: signalQSemN :: QSemN -> Int -> IO ()
+ Hledger.Cli.Script: some :: Alternative f => f a -> f [a]
+ Hledger.Cli.Script: stderr :: Handle
+ Hledger.Cli.Script: stdin :: Handle
+ Hledger.Cli.Script: stdout :: Handle
+ Hledger.Cli.Script: strip1By :: (Char -> Bool) -> String -> String
+ Hledger.Cli.Script: strip1Char :: Char -> Char -> String -> String
+ Hledger.Cli.Script: stripBy :: (Char -> Bool) -> String -> String
+ Hledger.Cli.Script: swapMVar :: MVar a -> a -> IO a
+ Hledger.Cli.Script: takeMVar :: MVar a -> IO a
+ Hledger.Cli.Script: threadCapability :: ThreadId -> IO (Int, Bool)
+ Hledger.Cli.Script: threadDelay :: Int -> IO ()
+ Hledger.Cli.Script: threadWaitRead :: Fd -> IO ()
+ Hledger.Cli.Script: threadWaitReadSTM :: Fd -> IO (STM (), IO ())
+ Hledger.Cli.Script: threadWaitWrite :: Fd -> IO ()
+ Hledger.Cli.Script: threadWaitWriteSTM :: Fd -> IO (STM (), IO ())
+ Hledger.Cli.Script: throwTo :: Exception e => ThreadId -> e -> IO ()
+ Hledger.Cli.Script: toLower :: Char -> Char
+ Hledger.Cli.Script: toTitle :: Char -> Char
+ Hledger.Cli.Script: toUpper :: Char -> Char
+ Hledger.Cli.Script: tryIOError :: IO a -> IO (Either IOError a)
+ Hledger.Cli.Script: tryPutMVar :: MVar a -> a -> IO Bool
+ Hledger.Cli.Script: tryReadMVar :: MVar a -> IO (Maybe a)
+ Hledger.Cli.Script: tryTakeMVar :: MVar a -> IO (Maybe a)
+ Hledger.Cli.Script: type IOError = IOException
+ Hledger.Cli.Script: universalNewlineMode :: NewlineMode
+ Hledger.Cli.Script: userError :: String -> IOError
+ Hledger.Cli.Script: userErrorType :: IOErrorType
+ Hledger.Cli.Script: utf16 :: TextEncoding
+ Hledger.Cli.Script: utf16be :: TextEncoding
+ Hledger.Cli.Script: utf16le :: TextEncoding
+ Hledger.Cli.Script: utf32 :: TextEncoding
+ Hledger.Cli.Script: utf32be :: TextEncoding
+ Hledger.Cli.Script: utf32le :: TextEncoding
+ Hledger.Cli.Script: utf8 :: TextEncoding
+ Hledger.Cli.Script: utf8_bom :: TextEncoding
+ Hledger.Cli.Script: waitQSem :: QSem -> IO ()
+ Hledger.Cli.Script: waitQSemN :: QSemN -> Int -> IO ()
+ Hledger.Cli.Script: withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
+ Hledger.Cli.Script: withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
+ Hledger.Cli.Script: withMVar :: MVar a -> (a -> IO b) -> IO b
+ Hledger.Cli.Script: withMVarMasked :: MVar a -> (a -> IO b) -> IO b
+ Hledger.Cli.Script: writeChan :: Chan a -> a -> IO ()
+ Hledger.Cli.Script: writeFile :: FilePath -> String -> IO ()
+ Hledger.Cli.Script: writeList2Chan :: Chan a -> [a] -> IO ()
+ Hledger.Cli.Script: yield :: IO ()
- Hledger.Cli.CliOptions: available_width :: HasCliOpts c_aivv => Lens' c_aivv Int
+ Hledger.Cli.CliOptions: available_width :: HasCliOpts c_aiA8 => Lens' c_aiA8 Int
- Hledger.Cli.CliOptions: class HasCliOpts c_aivv
+ Hledger.Cli.CliOptions: class HasCliOpts c_aiA8
- Hledger.Cli.CliOptions: cliOpts :: HasCliOpts c_aivv => Lens' c_aivv CliOpts
+ Hledger.Cli.CliOptions: cliOpts :: HasCliOpts c_aiA8 => Lens' c_aiA8 CliOpts
- Hledger.Cli.CliOptions: command :: HasCliOpts c_aivv => Lens' c_aivv String
+ Hledger.Cli.CliOptions: command :: HasCliOpts c_aiA8 => Lens' c_aiA8 String
- Hledger.Cli.CliOptions: debug__ :: HasCliOpts c_aivv => Lens' c_aivv Int
+ Hledger.Cli.CliOptions: debug__ :: HasCliOpts c_aiA8 => Lens' c_aiA8 Int
- Hledger.Cli.CliOptions: file__ :: HasCliOpts c_aivv => Lens' c_aivv [FilePath]
+ Hledger.Cli.CliOptions: file__ :: HasCliOpts c_aiA8 => Lens' c_aiA8 [FilePath]
- Hledger.Cli.CliOptions: inputopts :: HasCliOpts c_aivv => Lens' c_aivv InputOpts
+ Hledger.Cli.CliOptions: inputopts :: HasCliOpts c_aiA8 => Lens' c_aiA8 InputOpts
- Hledger.Cli.CliOptions: no_new_accounts :: HasCliOpts c_aivv => Lens' c_aivv Bool
+ Hledger.Cli.CliOptions: no_new_accounts :: HasCliOpts c_aiA8 => Lens' c_aiA8 Bool
- Hledger.Cli.CliOptions: output_file :: HasCliOpts c_aivv => Lens' c_aivv (Maybe FilePath)
+ Hledger.Cli.CliOptions: output_file :: HasCliOpts c_aiA8 => Lens' c_aiA8 (Maybe FilePath)
- Hledger.Cli.CliOptions: output_format :: HasCliOpts c_aivv => Lens' c_aivv (Maybe String)
+ Hledger.Cli.CliOptions: output_format :: HasCliOpts c_aiA8 => Lens' c_aiA8 (Maybe String)
- Hledger.Cli.CliOptions: progstarttime :: HasCliOpts c_aivv => Lens' c_aivv POSIXTime
+ Hledger.Cli.CliOptions: progstarttime :: HasCliOpts c_aiA8 => Lens' c_aiA8 POSIXTime
- Hledger.Cli.CliOptions: rawopts__ :: HasCliOpts c_aivv => Lens' c_aivv RawOpts
+ Hledger.Cli.CliOptions: rawopts__ :: HasCliOpts c_aiA8 => Lens' c_aiA8 RawOpts
- Hledger.Cli.CliOptions: reportspec :: HasCliOpts c_aivv => Lens' c_aivv ReportSpec
+ Hledger.Cli.CliOptions: reportspec :: HasCliOpts c_aiA8 => Lens' c_aiA8 ReportSpec
- Hledger.Cli.CliOptions: width__ :: HasCliOpts c_aivv => Lens' c_aivv (Maybe String)
+ Hledger.Cli.CliOptions: width__ :: HasCliOpts c_aiA8 => Lens' c_aiA8 (Maybe String)
- Hledger.Cli.Script: available_width :: HasCliOpts c_aivv => Lens' c_aivv Int
+ Hledger.Cli.Script: available_width :: HasCliOpts c_aiA8 => Lens' c_aiA8 Int
- Hledger.Cli.Script: class HasCliOpts c_aivv
+ Hledger.Cli.Script: class HasCliOpts c_aiA8
- Hledger.Cli.Script: cliOpts :: HasCliOpts c_aivv => Lens' c_aivv CliOpts
+ Hledger.Cli.Script: cliOpts :: HasCliOpts c_aiA8 => Lens' c_aiA8 CliOpts
- Hledger.Cli.Script: command :: HasCliOpts c_aivv => Lens' c_aivv String
+ Hledger.Cli.Script: command :: HasCliOpts c_aiA8 => Lens' c_aiA8 String
- Hledger.Cli.Script: debug__ :: HasCliOpts c_aivv => Lens' c_aivv Int
+ Hledger.Cli.Script: debug__ :: HasCliOpts c_aiA8 => Lens' c_aiA8 Int
- Hledger.Cli.Script: file__ :: HasCliOpts c_aivv => Lens' c_aivv [FilePath]
+ Hledger.Cli.Script: file__ :: HasCliOpts c_aiA8 => Lens' c_aiA8 [FilePath]
- Hledger.Cli.Script: infixl 1 >>
+ Hledger.Cli.Script: infixl 1 <&>
- Hledger.Cli.Script: infixl 4 <$!>
+ Hledger.Cli.Script: infixl 4 <**>
- Hledger.Cli.Script: inputopts :: HasCliOpts c_aivv => Lens' c_aivv InputOpts
+ Hledger.Cli.Script: inputopts :: HasCliOpts c_aiA8 => Lens' c_aiA8 InputOpts
- Hledger.Cli.Script: no_new_accounts :: HasCliOpts c_aivv => Lens' c_aivv Bool
+ Hledger.Cli.Script: no_new_accounts :: HasCliOpts c_aiA8 => Lens' c_aiA8 Bool
- Hledger.Cli.Script: output_file :: HasCliOpts c_aivv => Lens' c_aivv (Maybe FilePath)
+ Hledger.Cli.Script: output_file :: HasCliOpts c_aiA8 => Lens' c_aiA8 (Maybe FilePath)
- Hledger.Cli.Script: output_format :: HasCliOpts c_aivv => Lens' c_aivv (Maybe String)
+ Hledger.Cli.Script: output_format :: HasCliOpts c_aiA8 => Lens' c_aiA8 (Maybe String)
- Hledger.Cli.Script: progstarttime :: HasCliOpts c_aivv => Lens' c_aivv POSIXTime
+ Hledger.Cli.Script: progstarttime :: HasCliOpts c_aiA8 => Lens' c_aiA8 POSIXTime
- Hledger.Cli.Script: rawopts__ :: HasCliOpts c_aivv => Lens' c_aivv RawOpts
+ Hledger.Cli.Script: rawopts__ :: HasCliOpts c_aiA8 => Lens' c_aiA8 RawOpts
- Hledger.Cli.Script: reportspec :: HasCliOpts c_aivv => Lens' c_aivv ReportSpec
+ Hledger.Cli.Script: reportspec :: HasCliOpts c_aiA8 => Lens' c_aiA8 ReportSpec
- Hledger.Cli.Script: width__ :: HasCliOpts c_aivv => Lens' c_aivv (Maybe String)
+ Hledger.Cli.Script: width__ :: HasCliOpts c_aiA8 => Lens' c_aiA8 (Maybe String)
Files
- CHANGES.md +29/−0
- Hledger/Cli/Commands/Close.txt +0/−5
- Hledger/Cli/Commands/Stats.hs +5/−5
- Hledger/Cli/Script.hs +6/−0
- Hledger/Cli/Utils.hs +2/−2
- embeddedfiles/hledger-ui.1 +2/−2
- embeddedfiles/hledger-ui.info +35/−35
- embeddedfiles/hledger-ui.txt +2/−2
- embeddedfiles/hledger-web.1 +2/−2
- embeddedfiles/hledger-web.info +21/−21
- embeddedfiles/hledger-web.txt +3/−3
- embeddedfiles/hledger.1 +2/−2
- embeddedfiles/hledger.info +10942/−10942
- embeddedfiles/hledger.txt +3/−3
- hledger.1 +2/−2
- hledger.cabal +12/−12
- hledger.info +10942/−10942
- hledger.txt +3/−3
CHANGES.md view
@@ -9,6 +9,35 @@ User-visible changes in the hledger command line tool and library. +# 1.29.1 2023-03-16++Improvements++- Hledger.Cli.Script now also exports++ Control.Applicative+ Control.Concurrent+ Data.Char+ Data.Functor+ System.IO+ System.IO.Error++ and new string helpers++ strip1Char+ stripBy+ strip1By++- Allow building with GHC 9.6.1 (#2011)++Fixes++- The stats report no longer displays "Exact" in front of dates. (#2012)++Docs++- remove duplicate in `hledger close` docs (Yehoshua Pesach Wallach)+ # 1.29 2023-03-11 Breaking changes
Hledger/Cli/Commands/Close.txt view
@@ -42,11 +42,6 @@ With --interleaved, each equity posting is shown next to the corresponding source/destination posting. -The default closing date is yesterday or the journal's end date,-whichever is later. You can change this by specifying a report end date;-the last day of the report period will be the closing date. Eg -e 2022-means "close on 2022-12-31".- The default closing date is yesterday, or the journal's end date, whichever is later. You can change this by specifying a report end date; (The report start date does not matter.) The last day of the report
Hledger/Cli/Commands/Stats.hs view
@@ -70,7 +70,7 @@ (stts, tnum) = ([ ("Main file", path) -- ++ " (from " ++ source ++ ")") ,("Included files", unlines $ drop 1 $ journalFilePaths j)- ,("Transactions span", printf "%s to %s (%d days)" (start spn) (end spn) days)+ ,("Transactions span", printf "%s to %s (%d days)" (showstart spn) (showend spn) days) ,("Last transaction", maybe "none" show lastdate ++ showelapsed lastelapsed) ,("Transactions", printf "%d (%0.1f per day)" tnum txnrate) ,("Transactions last 30 days", printf "%d (%0.1f per day)" tnum30 txnrate30)@@ -100,10 +100,10 @@ direction | dys >= 0 = "days ago" :: String | otherwise = "days from now" tnum1 = length ts -- Integer would be better- start (DateSpan (Just d) _) = show d- start _ = ""- end (DateSpan _ (Just d)) = show d- end _ = ""+ showstart (DateSpan (Just efd) _) = show $ fromEFDay efd+ showstart _ = ""+ showend (DateSpan _ (Just efd)) = show $ fromEFDay efd+ showend _ = "" days = fromMaybe 0 $ daysInSpan spn txnrate | days==0 = 0 | otherwise = fromIntegral tnum1 / fromIntegral days :: Double
Hledger/Cli/Script.hs view
@@ -10,8 +10,12 @@ ) where +import Control.Applicative as Script+import Control.Concurrent as Script import Control.Monad as Script+import Data.Char as Script import Data.Either as Script+import Data.Functor as Script import Data.List as Script import Data.Maybe as Script import Data.Ord as Script@@ -26,6 +30,8 @@ import System.Environment as Script import System.Exit as Script import System.FilePath as Script+import System.IO as Script+import System.IO.Error as Script import System.Process as Script import Hledger as Script
Hledger/Cli/Utils.hs view
@@ -31,8 +31,8 @@ where import Control.Exception as C-import Control.Monad.Except (ExceptT, liftIO)-+import Control.Monad.Except (ExceptT)+import Control.Monad.IO.Class (liftIO) import Data.List import Data.Maybe import qualified Data.Text as T
embeddedfiles/hledger-ui.1 view
@@ -1,5 +1,5 @@ -.TH "HLEDGER-UI" "1" "March 2023" "hledger-ui-1.29 " "hledger User Manuals"+.TH "HLEDGER-UI" "1" "March 2023" "hledger-ui-1.29.1 " "hledger User Manuals" @@ -15,7 +15,7 @@ \f[V]hledger ui -- [OPTIONS] [QUERYARGS]\f[R] .SH DESCRIPTION .PP-This manual is for hledger\[aq]s terminal interface, version 1.29.+This manual is for hledger\[aq]s terminal interface, version 1.29.1. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user-friendly, cross-platform set of programs for
embeddedfiles/hledger-ui.info view
@@ -16,7 +16,7 @@ ‘hledger-ui [OPTIONS] [QUERYARGS]’ ‘hledger ui -- [OPTIONS] [QUERYARGS]’ - This manual is for hledger’s terminal interface, version 1.29. See+ This manual is for hledger’s terminal interface, version 1.29.1. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs@@ -706,40 +706,40 @@ Tag Table: Node: Top223-Node: OPTIONS1869-Ref: #options1967-Node: MOUSE7334-Ref: #mouse7429-Node: KEYS7672-Ref: #keys7765-Node: SCREENS12524-Ref: #screens12622-Node: Menu13330-Ref: #menu13422-Node: All accounts13499-Ref: #all-accounts13638-Node: Balance sheet accounts13897-Ref: #balance-sheet-accounts14077-Node: Income statement accounts14269-Ref: #income-statement-accounts14451-Node: Register16945-Ref: #register17082-Node: Transaction19110-Ref: #transaction19233-Node: Error20117-Ref: #error20211-Node: TIPS20455-Ref: #tips20554-Node: Watch mode20596-Ref: #watch-mode20703-Node: Debug output22191-Ref: #debug-output22302-Node: ENVIRONMENT22522-Ref: #environment22633-Node: FILES24056-Ref: #files24155-Node: BUGS24415-Ref: #bugs24492+Node: OPTIONS1871+Ref: #options1969+Node: MOUSE7336+Ref: #mouse7431+Node: KEYS7674+Ref: #keys7767+Node: SCREENS12526+Ref: #screens12624+Node: Menu13332+Ref: #menu13424+Node: All accounts13501+Ref: #all-accounts13640+Node: Balance sheet accounts13899+Ref: #balance-sheet-accounts14079+Node: Income statement accounts14271+Ref: #income-statement-accounts14453+Node: Register16947+Ref: #register17084+Node: Transaction19112+Ref: #transaction19235+Node: Error20119+Ref: #error20213+Node: TIPS20457+Ref: #tips20556+Node: Watch mode20598+Ref: #watch-mode20705+Node: Debug output22193+Ref: #debug-output22304+Node: ENVIRONMENT22524+Ref: #environment22635+Node: FILES24058+Ref: #files24157+Node: BUGS24417+Ref: #bugs24494 End Tag Table
embeddedfiles/hledger-ui.txt view
@@ -11,7 +11,7 @@ hledger ui -- [OPTIONS] [QUERYARGS] DESCRIPTION- This manual is for hledger's terminal interface, version 1.29. See+ This manual is for hledger's terminal interface, version 1.29.1. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for@@ -598,4 +598,4 @@ -hledger-ui-1.29 March 2023 HLEDGER-UI(1)+hledger-ui-1.29.1 March 2023 HLEDGER-UI(1)
embeddedfiles/hledger-web.1 view
@@ -1,5 +1,5 @@ -.TH "HLEDGER-WEB" "1" "March 2023" "hledger-web-1.29 " "hledger User Manuals"+.TH "HLEDGER-WEB" "1" "March 2023" "hledger-web-1.29.1 " "hledger User Manuals" @@ -23,7 +23,7 @@ \f[V]hledger web -- [OPTIONS] [QUERYARGS]\f[R] # start from hledger .SH DESCRIPTION .PP-This manual is for hledger\[aq]s web interface, version 1.29.+This manual is for hledger\[aq]s web interface, version 1.29.1. See also the hledger manual for common concepts and file formats. .PP hledger is a robust, user-friendly, cross-platform set of programs for
embeddedfiles/hledger-web.info view
@@ -18,7 +18,7 @@ ‘hledger-web --serve-api [OPTIONS] # run JSON server only’ ‘hledger web -- [OPTIONS] [QUERYARGS]’ # start from hledger - This manual is for hledger’s web interface, version 1.29. See also+ This manual is for hledger’s web interface, version 1.29.1. See also the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs@@ -664,26 +664,26 @@ Tag Table: Node: Top225-Node: OPTIONS2724-Ref: #options2829-Node: PERMISSIONS10623-Ref: #permissions10762-Node: EDITING UPLOADING DOWNLOADING12020-Ref: #editing-uploading-downloading12201-Node: RELOADING13043-Ref: #reloading13177-Node: JSON API13610-Ref: #json-api13725-Node: DEBUG OUTPUT19257-Ref: #debug-output19382-Node: Debug output19409-Ref: #debug-output-119510-Node: ENVIRONMENT19935-Ref: #environment20055-Node: FILES21404-Ref: #files21504-Node: BUGS21764-Ref: #bugs21842+Node: OPTIONS2726+Ref: #options2831+Node: PERMISSIONS10625+Ref: #permissions10764+Node: EDITING UPLOADING DOWNLOADING12022+Ref: #editing-uploading-downloading12203+Node: RELOADING13045+Ref: #reloading13179+Node: JSON API13612+Ref: #json-api13727+Node: DEBUG OUTPUT19259+Ref: #debug-output19384+Node: Debug output19411+Ref: #debug-output-119512+Node: ENVIRONMENT19937+Ref: #environment20057+Node: FILES21406+Ref: #files21506+Node: BUGS21766+Ref: #bugs21844 End Tag Table
embeddedfiles/hledger-web.txt view
@@ -13,8 +13,8 @@ hledger web -- [OPTIONS] [QUERYARGS] # start from hledger DESCRIPTION- This manual is for hledger's web interface, version 1.29. See also the- hledger manual for common concepts and file formats.+ This manual is for hledger's web interface, version 1.29.1. See also+ the hledger manual for common concepts and file formats. hledger is a robust, user-friendly, cross-platform set of programs for tracking money, time, or any other commodity, using double-entry@@ -608,4 +608,4 @@ -hledger-web-1.29 March 2023 HLEDGER-WEB(1)+hledger-web-1.29.1 March 2023 HLEDGER-WEB(1)
embeddedfiles/hledger.1 view
@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "March 2023" "hledger-1.29 " "hledger User Manuals"+.TH "HLEDGER" "1" "March 2023" "hledger-1.29.1 " "hledger User Manuals" @@ -26,7 +26,7 @@ hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP-This manual is for hledger\[aq]s command line interface, version 1.29.+This manual is for hledger\[aq]s command line interface, version 1.29.1. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well!
embeddedfiles/hledger.info view
@@ -23,10948 +23,10948 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger’s command line interface, version 1.29.-It also describes the common options, file formats and concepts used by-all hledger programs. It might accidentally teach you some-bookkeeping/accounting as well! You don’t need to know everything in-here to use hledger productively, but when you have a question about-functionality, this doc should answer it. It is detailed, so do skip-ahead or skim when needed. You can read it on hledger.org, or as an-info manual or man page on your system. You can also get it from-hledger itself with-‘hledger --man’, ‘hledger --info’ or ‘hledger help [TOPIC]’.-- The main function of the hledger CLI is to read plain text files-describing financial transactions, crunch the numbers, and print a-useful report on the terminal (or save it as HTML, CSV, JSON or SQL).-Many reports are available, as subcommands. hledger will also detect-other ‘hledger-*’ executables as extra subcommands.-- hledger reads data from one or more files in journal, timeclock,-timedot, or CSV format. The default file is ‘.hledger.journal’ in your-home directory; this can be overridden with one or more ‘-f FILE’-options, or the ‘LEDGER_FILE’ environment variable. hledger CLI can-also read from stdin with ‘-f-’; more on that below.-- Here is a small but valid hledger journal file describing one-transaction:--2015-10-16 bought food- expenses:food $10- assets:cash-- Transactions are dated movements of money (etc.) between two or more-_accounts_: bank accounts, your wallet, revenue/expense categories,-people, etc. You can choose any account names you wish, using ‘:’ to-indicate subaccounts. There must be at least two spaces between account-name and amount. Positive amounts are inflow to that account (_debit_),-negatives are outflow from it (_credit_). (Some reports show revenue,-liability and equity account balances as negative numbers as a result;-this is normal.)-- hledger’s add command can help you add transactions, or you can-install other data entry UIs like hledger-web or hledger-iadd. For more-extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM-+ vim-ledger, or VS Code + hledger-vscode are some good choices (see-https://hledger.org/editors.html).-- To get started, run ‘hledger add’ and follow the prompts, or save-some entries like the above in ‘$HOME/.hledger.journal’, then try-commands like:-‘hledger print -x’-‘hledger aregister assets’-‘hledger balance’-‘hledger balancesheet’-‘hledger incomestatement’.-Run ‘hledger’ to list the commands. See also the "Starting a journal-file" and "Setting opening balances" sections in PART 5: COMMON TASKS.--* Menu:--* PART 1 USER INTERFACE::-* Options::-* Environment::-* Input::-* Commands::-* Output::-* Limitations::-* Troubleshooting::-* PART 2 DATA FORMATS::-* Journal::-* CSV::-* Timeclock::-* Timedot::-* PART 3 REPORTING CONCEPTS::-* Time periods::-* Depth::-* Queries::-* Pivoting::-* Generating data::-* Forecasting::-* Budgeting::-* Cost reporting::-* Valuation::-* PART 4 COMMANDS::-* PART 5 COMMON TASKS::---File: hledger.info, Node: PART 1 USER INTERFACE, Next: Options, Prev: Top, Up: Top--1 PART 1: USER INTERFACE-************************---File: hledger.info, Node: Options, Next: Environment, Prev: PART 1 USER INTERFACE, Up: Top--2 Options-*********--* Menu:--* General options::-* Command options::-* Command arguments::-* Special characters::-* Unicode characters::-* Regular expressions::---File: hledger.info, Node: General options, Next: Command options, Up: Options--2.1 General options-===================--To see general usage help, including general options which are supported-by most hledger commands, run ‘hledger -h’.-- General help options:--‘-h --help’-- show general or COMMAND help-‘--man’-- show general or COMMAND user manual with man-‘--info’-- show general or COMMAND user manual with info-‘--version’-- show general or ADDONCMD version-‘--debug[=N]’-- show debug output (levels 1-9, default: 1)-- General input options:--‘-f FILE --file=FILE’-- use a different input file. For stdin, use - (default:- ‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’)-‘--rules-file=RULESFILE’-- Conversion rules file to use when reading CSV (default: FILE.rules)-‘--separator=CHAR’-- Field separator to expect when reading CSV (default: ’,’)-‘--alias=OLD=NEW’-- rename accounts named OLD to NEW-‘--anon’-- anonymize accounts and payees-‘--pivot FIELDNAME’-- use some other field or tag for the account name-‘-I --ignore-assertions’-- disable balance assertion checks (note: does not disable balance- assignments)-‘-s --strict’-- do extra error checking (check that all posted accounts are- declared)-- General reporting options:--‘-b --begin=DATE’-- include postings/txns on or after this date (will be adjusted to- preceding subperiod start when using a report interval)-‘-e --end=DATE’-- include postings/txns before this date (will be adjusted to- following subperiod end when using a report interval)-‘-D --daily’-- multiperiod/multicolumn report by day-‘-W --weekly’-- multiperiod/multicolumn report by week-‘-M --monthly’-- multiperiod/multicolumn report by month-‘-Q --quarterly’-- multiperiod/multicolumn report by quarter-‘-Y --yearly’-- multiperiod/multicolumn report by year-‘-p --period=PERIODEXP’-- set start date, end date, and/or reporting interval all at once- using period expressions syntax-‘--date2’-- match the secondary date instead (see command help for other- effects)-‘--today=DATE’-- override today’s date (affects relative smart dates, for- tests/examples)-‘-U --unmarked’-- include only unmarked postings/txns (can combine with -P or -C)-‘-P --pending’-- include only pending postings/txns-‘-C --cleared’-- include only cleared postings/txns-‘-R --real’-- include only non-virtual postings-‘-NUM --depth=NUM’-- hide/aggregate accounts or postings more than NUM levels deep-‘-E --empty’-- show items with zero amount, normally hidden (and vice-versa in- hledger-ui/hledger-web)-‘-B --cost’-- convert amounts to their cost/selling amount at transaction time-‘-V --market’-- convert amounts to their market value in default valuation- commodities-‘-X --exchange=COMM’-- convert amounts to their market value in commodity COMM-‘--value’-- convert amounts to cost or market value, more flexibly than- -B/-V/-X-‘--infer-market-prices’-- use transaction prices (recorded with @ or @@) as additional market- prices, as if they were P directives-‘--auto’-- apply automated posting rules to modify transactions.-‘--forecast’-- generate future transactions from periodic transaction rules, for- the next 6 months or till report end date. In hledger-ui, also- make ordinary future transactions visible.-‘--commodity-style’-- Override the commodity style in the output for the specified- commodity. For example ’EUR1.000,00’.-‘--color=WHEN (or --colour=WHEN)’-- Should color-supporting commands use ANSI color codes in text- output. ’auto’ (default): whenever stdout seems to be a- color-supporting terminal. ’always’ or ’yes’: always, useful eg- when piping output into ’less -R’. ’never’ or ’no’: never. A- NO_COLOR environment variable overrides this.-‘--pretty[=WHEN]’-- Show prettier output, e.g. using unicode box-drawing characters.- Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’- also work). If you provide an argument you must use ’=’, e.g.- ’–pretty=yes’.-- When a reporting option appears more than once in the command line,-the last one takes precedence.-- Some reporting options can also be written as query arguments.---File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: Options--2.2 Command options-===================--To see options for a particular command, including command-specific-options, run: ‘hledger COMMAND -h’.-- Command-specific options must be written after the command name, eg:-‘hledger print -x’.-- Additionally, if the command is an add-on, you may need to put its-options after a double-hyphen, eg: ‘hledger ui -- --watch’. Or, you can-run the add-on executable directly: ‘hledger-ui --watch’.---File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: Options--2.3 Command arguments-=====================--Most hledger commands accept arguments after the command name, which are-often a query, filtering the data in some way.-- You can save a set of command line options/arguments in a file, and-then reuse them by writing ‘@FILENAME’ as a command line argument. Eg:-‘hledger bal @foo.args’. (To prevent this, eg if you have an argument-that begins with a literal ‘@’, precede it with ‘--’, eg: ‘hledger bal--- @ARG’).-- Inside the argument file, each line should contain just one option or-argument. Avoid the use of spaces, except inside quotes (or you’ll see-a confusing error). Between a flag and its argument, use = (or-nothing). Bad:--assets depth:2--X USD-- Good:--assets-depth:2--X=USD-- For special characters (see below), use one less level of quoting-than you would at the command prompt. Bad:---X"$"-- Good:---X$-- See also: Save frequently used options.---File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: Options--2.4 Special characters-======================--* Menu:--* Single escaping shell metacharacters::-* Double escaping regular expression metacharacters::-* Triple escaping for add-on commands::-* Less escaping::---File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters--2.4.1 Single escaping (shell metacharacters)-----------------------------------------------In shell command lines, characters significant to your shell - such as-spaces, ‘<’, ‘>’, ‘(’, ‘)’, ‘|’, ‘$’ and ‘\’ - should be "shell-escaped"-if you want hledger to see them. This is done by enclosing them in-single or double quotes, or by writing a backslash before them. Eg to-match an account name containing a space:--$ hledger register 'credit card'-- or:--$ hledger register credit\ card-- Windows users should keep in mind that ‘cmd’ treats single quote as a-regular character, so you should be using double quotes exclusively.-PowerShell treats both single and double quotes as quotes.---File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters--2.4.2 Double escaping (regular expression metacharacters)------------------------------------------------------------Characters significant in regular expressions (described below) - such-as ‘.’, ‘^’, ‘$’, ‘[’, ‘]’, ‘(’, ‘)’, ‘|’, and ‘\’ - may need to be-"regex-escaped" if you don’t want them to be interpreted by hledger’s-regular expression engine. This is done by writing backslashes before-them, but since backslash is typically also a shell metacharacter, both-shell-escaping and regex-escaping will be needed. Eg to match a literal-‘$’ sign while using the bash shell:--$ hledger balance cur:'\$'-- or:--$ hledger balance cur:\\$---File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters--2.4.3 Triple escaping (for add-on commands)----------------------------------------------When you use hledger to run an external add-on command (described-below), one level of shell-escaping is lost from any options or-arguments intended for by the add-on command, so those need an extra-level of shell-escaping. Eg to match a literal ‘$’ sign while using the-bash shell and running an add-on command (‘ui’):--$ hledger ui cur:'\\$'-- or:--$ hledger ui cur:\\\\$-- If you wondered why _four_ backslashes, perhaps this helps:--unescaped: ‘$’-escaped: ‘\$’-double-escaped: ‘\\$’-triple-escaped: ‘\\\\$’-- Or, you can avoid the extra escaping by running the add-on executable-directly:--$ hledger-ui cur:\\$---File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters--2.4.4 Less escaping----------------------Options and arguments are sometimes used in places other than the shell-command line, where shell-escaping is not needed, so there you should-use one less level of escaping. Those places include:-- • an @argumentfile- • hledger-ui’s filter field- • hledger-web’s search form- • GHCI’s prompt (used by developers).---File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options--2.5 Unicode characters-======================--hledger is expected to handle non-ascii characters correctly:-- • they should be parsed correctly in input files and on the command- line, by all hledger tools (add, iadd, hledger-web’s- search/add/edit forms, etc.)-- • they should be displayed correctly by all hledger tools, and- on-screen alignment should be preserved.-- This requires a well-configured environment. Here are some tips:-- • A system locale must be configured, and it must be one that can- decode the characters being used. In bash, you can set a locale- like this: ‘export LANG=en_US.UTF-8’. There are some more details- in Troubleshooting. This step is essential - without it, hledger- will quit on encountering a non-ascii character (as with all- GHC-compiled programs).-- • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)- must support unicode-- • the terminal must be using a font which includes the required- unicode glyphs-- • the terminal should be configured to display wide characters as- double width (for report alignment)-- • on Windows, for best results you should run hledger in the same- kind of environment in which it was built. Eg hledger built in the- standard CMD.EXE environment (like the binaries on our download- page) might show display problems when run in a cygwin or msys- terminal, and vice versa. (See eg #961).---File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: Options--2.6 Regular expressions-=======================--hledger uses regular expressions in a number of places:-- • query terms, on the command line and in the hledger-web search- form: ‘REGEX’, ‘desc:REGEX’, ‘cur:REGEX’, ‘tag:...=REGEX’- • CSV rules conditional blocks: ‘if REGEX ...’- • account alias directive and ‘--alias’ option: ‘alias /REGEX/ =- REPLACEMENT’, ‘--alias /REGEX/=REPLACEMENT’-- hledger’s regular expressions come from the regex-tdfa library. If-they’re not doing what you expect, it’s important to know exactly what-they support:-- 1. they are case insensitive- 2. they are infix matching (they do not need to match the entire thing- being matched)- 3. they are POSIX ERE (extended regular expressions)- 4. they also support GNU word boundaries (‘\b’, ‘\B’, ‘\<’, ‘\>’)- 5. they do not support backreferences; if you write ‘\1’, it will- match the digit ‘1’. Except when doing text replacement, eg in- account aliases, where backreferences can be used in the- replacement string to reference capturing groups in the search- regexp.- 6. they do not support mode modifiers (‘(?s)’), character classes- (‘\w’, ‘\d’), or anything else not mentioned above.-- Some things to note:-- • In the ‘alias’ directive and ‘--alias’ option, regular expressions- must be enclosed in forward slashes (‘/REGEX/’). Elsewhere in- hledger, these are not required.-- • In queries, to match a regular expression metacharacter like ‘$’ as- a literal character, prepend a backslash. Eg to search for amounts- with the dollar sign in hledger-web, write ‘cur:\$’.-- • On the command line, some metacharacters like ‘$’ have a special- meaning to the shell and so must be escaped at least once more.- See Special characters.---File: hledger.info, Node: Environment, Next: Input, Prev: Options, Up: Top--3 Environment-*************--*LEDGER_FILE* The journal file path when not specified with ‘-f’.-- On unix computers, the default value is: ‘~/.hledger.journal’.-- A more typical value is something like ‘~/finance/YYYY.journal’,-where ‘~/finance’ is a version-controlled finance directory and YYYY is-the current year. Or, ‘~/finance/current.journal’, where-current.journal is a symbolic link to YYYY.journal.-- The usual way to set this permanently is to add a command to one of-your shell’s startup files (eg ‘~/.profile’):--export LEDGER_FILE=~/finance/current.journal`-- On some Mac computers, there is a more thorough way to set-environment variables, that will also affect applications started from-the GUI (eg, Emacs started from a dock icon): In-‘~/.MacOSX/environment.plist’, add an entry like:--{- "LEDGER_FILE" : "~/finance/current.journal"-}-- For this to take effect you might need to ‘killall Dock’, or reboot.-- On Windows computers, the default value is probably-‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a-command like this in a powershell window (let us know if you need to be-an Administrator, and if this persists across a reboot):--> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"-- Or, change it in settings: see-https://www.java.com/en/download/help/path.html.-- *COLUMNS* The screen width used by the register command. Default:-the full terminal width.-- *NO_COLOR* If this variable exists with any value, hledger will not-use ANSI color codes in terminal output. This is overriden by the-–color/–colour option.---File: hledger.info, Node: Input, Next: Commands, Prev: Environment, Up: Top--4 Input-*******--hledger reads transactions from one or more data files. The default-data file is ‘$HOME/.hledger.journal’ (or on Windows, something like-‘C:\Users\YOURNAME\.hledger.journal’).-- You can override this with the ‘$LEDGER_FILE’ environment variable:--$ setenv LEDGER_FILE ~/finance/2016.journal-$ hledger stats-- or with one or more ‘-f/--file’ options:--$ hledger -f /some/file -f another_file stats-- The file name ‘-’ means standard input:--$ cat some.journal | hledger -f---* Menu:--* Data formats::-* Multiple files::-* Strict mode::---File: hledger.info, Node: Data formats, Next: Multiple files, Up: Input--4.1 Data formats-================--Usually the data file is in hledger’s journal format, but it can be in-any of the supported file formats, which currently are:--Reader: Reads: Used for file- extensions:----------------------------------------------------------------------------‘journal’hledger journal files and some Ledger ‘.journal’ ‘.j’- journals, for transactions ‘.hledger’ ‘.ledger’-‘timeclock’timeclock files, for precise time ‘.timeclock’- logging-‘timedot’timedot files, for approximate time ‘.timedot’- logging-‘csv’ comma/semicolon/tab/other-separated ‘.csv’ ‘.ssv’ ‘.tsv’- values, for data import-- These formats are described in more detail below.-- hledger detects the format automatically based on the file extensions-shown above. If it can’t recognise the file extension, it assumes-‘journal’ format. So for non-journal files, it’s important to use a-recognised file extension, so as to either read successfully or to show-relevant error messages.-- You can also force a specific reader/format by prefixing the file-path with the format and a colon. Eg, to read a .dat file as csv-format:--$ hledger -f csv:/some/csv-file.dat stats-- Or to read stdin (‘-’) as timeclock format:--$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:----File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Data formats, Up: Input--4.2 Multiple files-==================--You can specify multiple ‘-f’ options, to read multiple files as one big-journal. There are some limitations with this:-- • most directives do not affect sibling files- • balance assertions will not see any account balances from previous- files-- If you need either of those things, you can-- • use a single parent file which includes the others- • or concatenate the files into one before reading, eg: ‘cat- a.journal b.journal | hledger -f- CMD’.---File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input--4.3 Strict mode-===============--hledger checks input files for valid data. By default, the most-important errors are detected, while still accepting easy journal files-without a lot of declarations:-- • Are the input files parseable, with valid syntax ?- • Are all transactions balanced ?- • Do all balance assertions pass ?-- With the ‘-s’/‘--strict’ flag, additional checks are performed:-- • Are all accounts posted to, declared with an ‘account’ directive ?- (Account error checking)- • Are all commodities declared with a ‘commodity’ directive ?- (Commodity error checking)- • Are all commodity conversions declared explicitly ?-- You can use the check command to run individual checks – the ones-listed above and some more.---File: hledger.info, Node: Commands, Next: Output, Prev: Input, Up: Top--5 Commands-**********--hledger provides a number of built-in subcommands (described below).-Most of these read your data without changing it, and display a report.-A few assist with data entry and management.-- Run ‘hledger’ with no arguments to list the commands available, and-‘hledger CMD’ to run a command. CMD can be the full command name, or-its standard abbreviation shown in the commands list, or any unambiguous-prefix of the name. Eg: ‘hledger bal’.--* Menu:--* Add-on commands::---File: hledger.info, Node: Add-on commands, Up: Commands--5.1 Add-on commands-===================--Add-on commands are extra subcommands provided by programs or scripts in-your PATH-- • whose name starts with ‘hledger-’- • whose name ends with a recognised file extension:- ‘.bat’,‘.com’,‘.exe’, ‘.hs’,‘.lhs’,‘.pl’,‘.py’,‘.rb’,‘.rkt’,‘.sh’- or none- • and (on unix, mac) which are executable by the current user.-- Addons can be written in any language, but haskell scripts or-programs have a big advantage: they can use hledger’s library code, for-command-line options, parsing and reporting.-- Several add-on commands are installed by the hledger-install script.-See https://hledger.org/scripts.html for more details.-- Note in a hledger command line, add-on command flags must have a-double dash (‘--’) preceding them. Eg you must write:--$ hledger web -- --serve-- and not:--$ hledger web --serve-- (because the ‘--serve’ flag belongs to ‘hledger-web’, not ‘hledger’).-- The ‘-h/--help’ and ‘--version’ flags don’t require ‘--’.-- If you have any trouble with this, remember you can always run the-add-on program directly, eg:--$ hledger-web --serve---File: hledger.info, Node: Output, Next: Limitations, Prev: Commands, Up: Top--6 Output-********--* Menu:--* Output destination::-* Output format::-* Commodity styles::-* Colour::-* Box-drawing::-* Debug output::---File: hledger.info, Node: Output destination, Next: Output format, Up: Output--6.1 Output destination-======================--hledger commands send their output to the terminal by default. You can-of course redirect this, eg into a file, using standard shell syntax:--$ hledger print > foo.txt-- Some commands (print, register, stats, the balance commands) also-provide the ‘-o/--output-file’ option, which does the same thing without-needing the shell. Eg:--$ hledger print -o foo.txt-$ hledger print -o - # write to stdout (the default)---File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output--6.2 Output format-=================--Some commands offer other kinds of output, not just text on the-terminal. Here are those commands and the formats currently supported:--- txt csv html json sql-------------------------------------------------------------------------------aregister Y Y Y Y-balance Y _1_ Y _1_ Y _1,2_ Y-balancesheet Y _1_ Y _1_ Y _1_ Y-balancesheetequity Y _1_ Y _1_ Y _1_ Y-cashflow Y _1_ Y _1_ Y _1_ Y-incomestatement Y _1_ Y _1_ Y _1_ Y-print Y Y Y Y-register Y Y Y-- • _1 Also affected by the balance commands’ ‘--layout’ option._- • _2 ‘balance’ does not support html output without a report interval- or with ‘--budget’._-- The output format is selected by the ‘-O/--output-format=FMT’ option:--$ hledger print -O csv # print CSV on stdout-- or by the filename extension of an output file specified with the-‘-o/--output-file=FILE.FMT’ option:--$ hledger balancesheet -o foo.csv # write CSV to foo.csv-- The ‘-O’ option can be combined with ‘-o’ to override the file-extension, if needed:--$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt-- Some notes about the various output formats:--* Menu:--* CSV output::-* HTML output::-* JSON output::-* SQL output::---File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format--6.2.1 CSV output------------------- • In CSV output, digit group marks (such as thousands separators) are- disabled automatically.---File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format--6.2.2 HTML output-------------------- • HTML output can be styled by an optional ‘hledger.css’ file in the- same directory.---File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format--6.2.3 JSON output-------------------- • This is not yet much used; real-world feedback is welcome.-- • Our JSON is rather large and verbose, since it is a faithful- representation of hledger’s internal data types. To understand the- JSON, read the Haskell type definitions, which are mostly in- https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.-- • hledger represents quantities as Decimal values storing up to 255- significant digits, eg for repeating decimals. Such numbers can- arise in practice (from automatically-calculated transaction- prices), and would break most JSON consumers. So in JSON, we show- quantities as simple Numbers with at most 10 decimal places. We- don’t limit the number of integer digits, but that part is under- your control. We hope this approach will not cause problems in- practice; if you find otherwise, please let us know. (Cf #1195)---File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format--6.2.4 SQL output------------------- • This is not yet much used; real-world feedback is welcome.-- • SQL output is expected to work with sqlite, MySQL and PostgreSQL-- • SQL output is structured with the expectations that statements will- be executed in the empty database. If you already have tables- created via SQL output of hledger, you would probably want to- either clear tables of existing data (via ‘delete’ or ‘truncate’- SQL statements) or drop tables completely as otherwise your- postings will be duped.---File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output--6.3 Commodity styles-====================--When displaying amounts, hledger infers a standard display style for-each commodity/currency, as described below in Commodity display style.-- If needed, this can be overridden by a ‘-c/--commodity-style’ option-(except for cost amounts and amounts displayed by the ‘print’ command,-which are always displayed with all decimal digits). For example, the-following will force dollar amounts to be displayed as shown:--$ hledger print -c '$1.000,0'-- This option can repeated to set the display style for multiple-commodities/currencies. Its argument is as described in the commodity-directive.---File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output--6.4 Colour-==========--In terminal output, some commands can produce colour when the terminal-supports it:-- • if the ‘--color/--colour’ option is given a value of ‘yes’ or- ‘always’ (or ‘no’ or ‘never’), colour will (or will not) be used;- • otherwise, if the ‘NO_COLOR’ environment variable is set, colour- will not be used;- • otherwise, colour will be used if the output (terminal or file)- supports it.---File: hledger.info, Node: Box-drawing, Next: Debug output, Prev: Colour, Up: Output--6.5 Box-drawing-===============--In terminal output, you can enable unicode box-drawing characters to-render prettier tables:-- • if the ‘--pretty’ option is given a value of ‘yes’ or ‘always’ (or- ‘no’ or ‘never’), unicode characters will (or will not) be used;- • otherwise, unicode characters will not be used.---File: hledger.info, Node: Debug output, Prev: Box-drawing, Up: Output--6.6 Debug output-================--We intend hledger to be relatively easy to troubleshoot, introspect and-develop. You can add ‘--debug[=N]’ to any hledger command line to see-additional debug output. N ranges from 1 (least output, the default) to-9 (maximum output). Typically you would start with 1 and increase until-you are seeing enough. Debug output goes to stderr, and is not affected-by ‘-o/--output-file’ (unless you redirect stderr to stdout, eg:-‘2>&1’). It will be interleaved with normal output, which can help-reveal when parts of the code are evaluated. To capture debug output in-a log file instead, you can usually redirect stderr, eg:--hledger bal --debug=3 2>hledger.log---File: hledger.info, Node: Limitations, Next: Troubleshooting, Prev: Output, Up: Top--7 Limitations-*************--The need to precede add-on command options with ‘--’ when invoked from-hledger is awkward.-- When input data contains non-ascii characters, a suitable system-locale must be configured (or there will be an unhelpful error). Eg on-POSIX, set LANG to something other than C.-- In a Microsoft Windows CMD window, non-ascii characters and colours-are not supported.-- On Windows, non-ascii characters may not display correctly when-running a hledger built in CMD in MSYS/CYGWIN, or vice-versa.-- In a Cygwin/MSYS/Mintty window, the tab key is not supported in-hledger add.-- Not all of Ledger’s journal file syntax is supported. See hledger-and Ledger > Differences > journal format.-- On large data files, hledger is slower and uses more memory than-Ledger.---File: hledger.info, Node: Troubleshooting, Next: PART 2 DATA FORMATS, Prev: Limitations, Up: Top--8 Troubleshooting-*****************--Here are some issues you might encounter when you run hledger (and-remember you can also seek help from the IRC channel, mail list or bug-tracker):-- *Successfully installed, but "No command ’hledger’ found"*-stack and cabal install binaries into a special directory, which should-be added to your PATH environment variable. Eg on unix-like systems,-that is ~/.local/bin and ~/.cabal/bin respectively.-- *I set a custom LEDGER_FILE, but hledger is still using the default-file*-‘LEDGER_FILE’ should be a real environment variable, not just a shell-variable. The command ‘env | grep LEDGER_FILE’ should show it. You may-need to use ‘export’. Here’s an explanation.-- *Getting errors like "Illegal byte sequence" or "Invalid or-incomplete multibyte or wide character" or "commitAndReleaseBuffer:-invalid argument (invalid character)"*-Programs compiled with GHC (hledger, haskell build tools, etc.) need to-have a UTF-8-aware locale configured in the environment, otherwise they-will fail with these kinds of errors when they encounter non-ascii-characters.-- To fix it, set the LANG environment variable to some locale which-supports UTF-8. The locale you choose must be installed on your system.-- Here’s an example of setting LANG temporarily, on Ubuntu GNU/Linux:--$ file my.journal-my.journal: UTF-8 Unicode text # the file is UTF8-encoded-$ echo $LANG-C # LANG is set to the default locale, which does not support UTF8-$ locale -a # which locales are installed ?-C-en_US.utf8 # here's a UTF8-aware one we can use-POSIX-$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command-- If available, ‘C.UTF-8’ will also work. If your preferred locale-isn’t listed by ‘locale -a’, you might need to install it. Eg on-Ubuntu/Debian:--$ apt-get install language-pack-fr-$ locale -a-C-en_US.utf8-fr_BE.utf8-fr_CA.utf8-fr_CH.utf8-fr_FR.utf8-fr_LU.utf8-POSIX-$ LANG=fr_FR.utf8 hledger -f my.journal print-- Here’s how you could set it permanently, if you use a bash shell:--$ echo "export LANG=en_US.utf8" >>~/.bash_profile-$ bash --login-- Exact spelling and capitalisation may be important. Note the-difference on MacOS (‘UTF-8’, not ‘utf8’). Some platforms (eg ubuntu)-allow variant spellings, but others (eg macos) require it to be exact:--$ locale -a | grep -iE en_us.*utf-en_US.UTF-8-$ LANG=en_US.UTF-8 hledger -f my.journal print---File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Troubleshooting, Up: Top--9 PART 2: DATA FORMATS-**********************---File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top--10 Journal-**********--hledger’s default file format, representing a General Journal. Here’s a-cheatsheet/mini-tutorial, or you can skip ahead to About journal format.--* Menu:--* Journal cheatsheet::-* About journal format::-* Comments::-* Transactions::-* Dates::-* Status::-* Code::-* Description::-* Transaction comments::-* Postings::-* Account names::-* Amounts::-* Costs::-* Balance assertions::-* Posting comments::-* Tags::-* Directives::-* account directive::-* alias directive::-* commodity directive::-* decimal-mark directive::-* include directive::-* P directive::-* payee directive::-* tag directive::-* Periodic transactions::-* Other syntax::---File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal--10.1 Journal cheatsheet-=======================--# Here is the main syntax of hledger's journal format-# (omitting extra Ledger compatibility syntax).-# hledger journals contain comments, directives, and transactions, in any order:--###############################################################################-# 1. Comment lines are for notes or temporarily disabling things.-# They begin with #, ;, or a line containing the word "comment".--# hash comment line-; semicolon comment line-comment-These lines-are commented.-end comment--# Some but not all hledger entries can have same-line comments attached to them,-# from ; (semicolon) to end of line.--###############################################################################-# 2. Directives modify parsing or reports in some way.-# They begin with a word or letter (or symbol).--account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;.-account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX)-alias chkg = assets:checking-commodity $0.00-decimal-mark .-include /dev/null-payee Whole Foods-P 2022-01-01 AAAA $1.40-~ monthly budget goals ; <- 2+ spaces between period expression and description- expenses:food $400- expenses:home $1000- budgeted--###############################################################################-# 3. Transactions are what it's all about; they are dated events,-# usually describing movements of money.-# They begin with a date.--# DATE DESCRIPTION ; This is a transaction comment.-# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment.-# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented.-# ; ^^ At least 2 spaces between account and amount.-# ... ; Any number of postings is allowed. The amounts must balance (sum to 0).--2022-01-01 opening balances are declared this way- assets:checking $1000 ; Account names can be anything. lower case is easy to type.- assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common.- assets:cash:wallet $100 ; : indicates subaccounts.- liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative.- equity ; One amount can be left blank; $-1900 is inferred here.--2022-04-15 * (#12345) pay taxes- ; There can be a ! or * after the date meaning "pending" or "cleared".- ; There can be a transaction code (text in parentheses) after the date/status.- ; Amounts' sign represents direction of flow, or credit/debit:- assets:checking $-500 ; minus means removed from this account (credit)- expenses:tax:us:2021 $500 ; plus means added to this account (debit)- ; revenue/expense categories are also "accounts"--Kv-2022-01-01 ; The description is optional.- ; Any currency/commodity symbols are allowed, on either side.- assets:cash:wallet GBP -10- expenses:clothing GBP 10- assets:gringotts -10 gold- assets:pouch 10 gold- revenues:gifts -2 "Liquorice Wands" ; Complex symbols- assets:bag 2 "Liquorice Wands" ; must be double-quoted.--2022-01-01 Cost in another commodity can be noted with @ or @@- assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost- assets:investments 3.0 AAAA @@ $4 ; @@ means total cost- assets:checking $-7.00--2022-01-02 assert balances- ; Balances can be asserted for extra error checking, in any transaction.- assets:investments 0 AAAA = 5.0 AAAA- assets:pouch 0 gold = 10 gold- assets:savings $0 = $1000--1999-12-31 Ordering transactions by date is recommended but not required.- ; Postings are not required.--2022.01.01 These date-2022/1/1 formats are-12/31 also allowed (but consistent YYYY-MM-DD is recommended).---File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal--10.2 About journal format-=========================--hledger’s usual data source is a plain text file containing journal-entries in hledger journal format. This file represents a standard-accounting general journal. I use file names ending in ‘.journal’, but-that’s not required. The journal file contains a number of transaction-entries, each describing a transfer of money (or any commodity) between-two or more named accounts, in a simple format readable by both hledger-and humans.-- hledger’s journal format is a compatible subset, mostly, of ledger’s-journal format, so hledger can work with compatible ledger journal files-as well. It’s safe, and encouraged, to run both hledger and ledger on-the same journal file, eg to validate the results you’re getting.-- You can use hledger without learning any more about this file; just-use the add or web or import commands to create and update it.-- Many users, though, edit the journal file with a text editor, and-track changes with a version control system such as git. Editor addons-such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and-hledger-vscode for Visual Studio Code, make this easier, adding colour,-formatting, tab completion, and useful commands. See Editor-configuration at hledger.org for the full list.-- Here’s a description of each part of the file format (and hledger’s-data model).-- A hledger journal file can contain three kinds of thing: file-comments, transactions, and/or directives (counting periodic transaction-rules and auto posting rules as directives).---File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal--10.3 Comments-=============--Lines in the journal will be ignored if they begin with a hash (‘#’) or-a semicolon (‘;’). (See also Other syntax.) hledger will also ignore-regions beginning with a ‘comment’ line and ending with an ‘end comment’-line (or file end). Here’s a suggestion for choosing between them:-- • ‘#’ for top-level notes- • ‘;’ for commenting out things temporarily- • ‘comment’ for quickly commenting large regions (remember it’s- there, or you might get confused)-- Eg:--# a comment line-; another commentline-comment-A multi-line comment block,-continuing until "end comment" directive-or the end of the current file.-end comment-- Some hledger entries can have same-line comments attached to them,-from ; (semicolon) to end of line. See Transaction comments, Posting-comments, and Account comments below.---File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal--10.4 Transactions-=================--Transactions are the main unit of information in a journal file. They-represent events, typically a movement of some quantity of commodities-between two or more named accounts.-- Each transaction is recorded as a journal entry, beginning with a-simple date in column 0. This can be followed by any of the following-optional fields, separated by spaces:-- • a status character (empty, ‘!’, or ‘*’)- • a code (any short number or text, enclosed in parentheses)- • a description (any remaining text until end of line or a semicolon)- • a comment (any remaining text following a semicolon until end of- line, and any following indented lines beginning with a semicolon)- • 0 or more indented _posting_ lines, describing what was transferred- and the accounts involved (indented comment lines are also allowed,- but not blank lines or non-indented lines).-- Here’s a simple journal file containing one transaction:--2008/01/01 income- assets:bank:checking $1- income:salary $-1---File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal--10.5 Dates-==========--* Menu:--* Simple dates::-* Posting dates::---File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates--10.5.1 Simple dates----------------------Dates in the journal file use _simple dates_ format: ‘YYYY-MM-DD’ or-‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, with leading zeros optional. The year may-be omitted, in which case it will be inferred from the context: the-current transaction, the default year set with a ‘Y’ directive, or the-current date when the command is run. Some examples: ‘2010-01-31’,-‘2010/01/31’, ‘2010.1.31’, ‘1/31’.-- (The UI also accepts simple dates, as well as the more flexible smart-dates documented in the hledger manual.)---File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates--10.5.2 Posting dates-----------------------You can give individual postings a different date from their parent-transaction, by adding a posting comment containing a tag (see below)-like ‘date:DATE’. This is probably the best way to control posting-dates precisely. Eg in this example the expense should appear in May-reports, and the deduction from checking should be reported on 6/1 for-easy bank reconciliation:--2015/5/30- expenses:food $10 ; food purchased on saturday 5/30- assets:checking ; bank cleared it on monday, date:6/1--$ hledger -f t.j register food-2015-05-30 expenses:food $10 $10--$ hledger -f t.j register checking-2015-06-01 assets:checking $-10 $-10-- DATE should be a simple date; if the year is not specified it will-use the year of the transaction’s date.-The ‘date:’ tag must have a valid simple date value if it is present, eg-a ‘date:’ tag with no value is not allowed.---File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal--10.6 Status-===========--Transactions, or individual postings within a transaction, can have a-status mark, which is a single character before the transaction-description or posting account name, separated from it by a space,-indicating one of three statuses:--mark status- ------------------- unmarked-‘!’ pending-‘*’ cleared-- When reporting, you can filter by status with the ‘-U/--unmarked’,-‘-P/--pending’, and ‘-C/--cleared’ flags; or the ‘status:’, ‘status:!’,-and ‘status:*’ queries; or the U, P, C keys in hledger-ui.-- Note, in Ledger and in older versions of hledger, the "unmarked"-state is called "uncleared". As of hledger 1.3 we have renamed it to-unmarked for clarity.-- To replicate Ledger and old hledger’s behaviour of also matching-pending, combine -U and -P.-- Status marks are optional, but can be helpful eg for reconciling with-real-world accounts. Some editor modes provide highlighting and-shortcuts for working with status. Eg in Emacs ledger-mode, you can-toggle transaction status with C-c C-e, or posting status with C-c C-c.-- What "uncleared", "pending", and "cleared" actually mean is up to-you. Here’s one suggestion:--status meaning----------------------------------------------------------------------------uncleared recorded but not yet reconciled; needs review-pending tentatively reconciled (if needed, eg during a big- reconciliation)-cleared complete, reconciled as far as possible, and considered- correct-- With this scheme, you would use ‘-PC’ to see the current balance at-your bank, ‘-U’ to see things which will probably hit your bank soon-(like uncashed checks), and no flags to see the most up-to-date state of-your finances.---File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal--10.7 Code-=========--After the status mark, but before the description, you can optionally-write a transaction "code", enclosed in parentheses. This is a good-place to record a check number, or some other important transaction id-or reference number.---File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal--10.8 Description-================--A transaction’s description is the rest of the line following the date-and status mark (or until a comment begins). Sometimes called the-"narration" in traditional bookkeeping, it can be used for whatever you-wish, or left blank. Transaction descriptions can be queried, unlike-comments.--* Menu:--* Payee and note::---File: hledger.info, Node: Payee and note, Up: Description--10.8.1 Payee and note------------------------You can optionally include a ‘|’ (pipe) character in descriptions to-subdivide the description into separate fields for payee/payer name on-the left (up to the first ‘|’) and an additional note field on the right-(after the first ‘|’). This may be worthwhile if you need to do more-precise querying and pivoting by payee or by note.---File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal--10.9 Transaction comments-=========================--Text following ‘;’, after a transaction description, and/or on indented-lines immediately below it, form comments for that transaction. They-are reproduced by ‘print’ but otherwise ignored, except they may contain-tags, which are not ignored.--2012-01-01 something ; a transaction comment- ; a second line of transaction comment- expenses 1- assets---File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal--10.10 Postings-==============--A posting is an addition of some amount to, or removal of some amount-from, an account. Each posting line begins with at least one space or-tab (2 or 4 spaces is common), followed by:-- • (optional) a status character (empty, ‘!’, or ‘*’), followed by a- space- • (required) an account name (any text, optionally containing *single- spaces*, until end of line or a double space)- • (optional) *two or more spaces* or tabs followed by an amount.-- Positive amounts are being added to the account, negative amounts are-being removed.-- The amounts within a transaction must always sum up to zero. As a-convenience, one amount may be left blank; it will be inferred so as to-balance the transaction.-- Be sure to note the unusual two-space delimiter between account name-and amount. This makes it easy to write account names containing-spaces. But if you accidentally leave only one space (or tab) before-the amount, the amount will be considered part of the account name.---File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal--10.11 Account names-===================--Accounts are the main way of categorising things in hledger. As in-Double Entry Bookkeeping, they can represent real world accounts (such-as a bank account), or more abstract categories such as "money borrowed-from Frank" or "money spent on electricity".-- You can use any account names you like, but we usually start with the-traditional accounting categories, which in english are ‘assets’,-‘liabilities’, ‘equity’, ‘revenues’, ‘expenses’. (You might see these-referred to as A, L, E, R, X for short.)-- For more precise reporting, we usually divide the top level accounts-into more detailed subaccounts, by writing a full colon between account-name parts. For example, from the account names ‘assets:bank:checking’-and ‘expenses:food’, hledger will infer this hierarchy of five accounts:--assets-assets:bank-assets:bank:checking-expenses-expenses:food-- Shown as an outline, the hierarchical tree structure is more clear:--assets- bank- checking-expenses- food-- hledger reports can summarise the account tree to any depth, so you-can go as deep as you like with subcategories, but keeping your account-names relatively simple may be best when starting out.-- Account names may be capitalised or not; they may contain letters,-numbers, symbols, or single spaces. Note, when an account name and an-amount are written on the same line, they must be separated by *two or-more spaces* (or tabs).-- Parentheses or brackets enclosing the full account name indicate-virtual postings, described below. Parentheses or brackets internal to-the account name have no special meaning.-- Account names can be altered temporarily or permanently by account-aliases.---File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal--10.12 Amounts-=============--After the account name, there is usually an amount. (Important: between-account name and amount, there must be *two or more spaces*.)-- hledger’s amount format is flexible, supporting several international-formats. Here are some examples. Amounts have a number (the-"quantity"):--1-- ..and usually a currency symbol or commodity name (more on this-below), to the left or right of the quantity, with or without a-separating space:--$1-4000 AAPL-3 "green apples"-- Amounts can be preceded by a minus sign (or a plus sign, though plus-is the default), The sign can be written before or after a left-side-commodity symbol:---$1-$-1-- One or more spaces between the sign and the number are acceptable-when parsing (but they won’t be displayed in output):--+ $1-$- 1-- Scientific E notation is allowed:--1E-6-EUR 1E3--* Menu:--* Decimal marks digit group marks::-* Commodity::-* Directives influencing number parsing and display::-* Commodity display style::-* Rounding::---File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts--10.12.1 Decimal marks, digit group marks-------------------------------------------A _decimal mark_ can be written as a period or a comma:--1.23-1,23456780000009-- In the integer part of the quantity (left of the decimal mark),-groups of digits can optionally be separated by a _digit group mark_ - a-space, comma, or period (different from the decimal mark):-- $1,000,000.00- EUR 2.000.000,00-INR 9,99,99,999.00- 1 000 000.9455-- Note, a number containing a single digit group mark and no decimal-mark is ambiguous. Are these digit group marks or decimal marks ?--1,000-1.000-- If you don’t tell it otherwise, hledger will assume both of the above-are decimal marks, parsing both numbers as 1.-- To prevent confusing parsing mistakes and undetected typos,-especially if your data contains digit group marks (eg, thousands-separators), we recommend explicitly declaring the decimal mark-character in each journal file, using a directive at the top of the-file. The ‘decimal-mark’ directive is best, otherwise ‘commodity’-directives will also work. These are described below.---File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts--10.12.2 Commodity--------------------Amounts in hledger have both a "quantity", which is a signed decimal-number, and a "commodity", which is a currency symbol, stock ticker, or-any word or phrase describing something you are tracking.-- If the commodity name contains non-letters (spaces, numbers, or-punctuation), you must always write it inside double quotes (‘"green-apples"’, ‘"ABC123"’).-- If you write just a bare number, that too will have a commodity, with-name ‘""’; we call that the "no-symbol commodity".-- Actually, hledger combines these single-commodity amounts into more-powerful multi-commodity amounts, which are what it works with most of-the time. A multi-commodity amount could be, eg: ‘1 USD, 2 EUR, 3.456-TSLA’. In practice, you will only see multi-commodity amounts in-hledger’s output; you can’t write them directly in the journal file.-- (If you are writing scripts or working with hledger’s internals,-these are the ‘Amount’ and ‘MixedAmount’ types.)---File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts--10.12.3 Directives influencing number parsing and display------------------------------------------------------------You can add ‘decimal-mark’ and ‘commodity’ directives to the journal, to-declare and control these things more explicitly and precisely. These-are described below, but here’s a quick example:--# the decimal mark character used by all amounts in this file (all commodities)-decimal-mark .--# display styles for the $, EUR, INR and no-symbol commodities:-commodity $1,000.00-commodity EUR 1.000,00-commodity INR 9,99,99,999.00-commodity 1 000 000.9455---File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts--10.12.4 Commodity display style----------------------------------For the amounts in each commodity, hledger chooses a consistent display-style to use in most reports. (Exceptions: price amounts, and all-amounts displayed by the ‘print’ command, are displayed with all of-their decimal digits visible.)-- A commodity’s display style is inferred as follows.-- First, if a default commodity is declared with ‘D’, this commodity-and its style is applied to any no-symbol amounts in the journal.-- Then each commodity’s style is inferred from one of the following, in-order of preference:-- • The commodity directive for that commodity (including the no-symbol- commodity), if any.- • The amounts in that commodity seen in the journal’s transactions.- (Posting amounts only; prices and periodic or auto rules are- ignored, currently.)- • The built-in fallback style, which looks like this: ‘$1000.00’.- (Symbol on the left, period decimal mark, two decimal places.)-- A style is inferred from journal amounts as follows:-- • Use the general style (decimal mark, symbol placement) of the first- amount- • Use the first-seen digit group style (digit group mark, digit group- sizes), if any- • Use the maximum number of decimal places of all.-- Cost amounts don’t affect the commodity display style directly, but-occasionally they can do so indirectly (eg when a posting’s amount is-inferred using a cost). If you find this causing problems, use a-commodity directive to fix the display style.-- To summarise: each commodity’s amounts will be normalised to (a) the-style declared by a ‘commodity’ directive, or (b) the style of the first-posting amount in the journal, with the first-seen digit group style and-the maximum-seen number of decimal places. So if your reports are-showing amounts in a way you don’t like, eg with too many decimal-places, use a commodity directive. Some examples:--# declare euro, dollar, bitcoin and no-symbol commodities and set their -# input number formats and output display styles:-commodity EUR 1.000,-commodity $1000.00-commodity 1000.00000000 BTC-commodity 1 000.-- The inferred commodity style can be overridden by supplying a command-line option.---File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts--10.12.5 Rounding-------------------Amounts are stored internally as decimal numbers with up to 255 decimal-places, and displayed with the number of decimal places specified by the-commodity display style. Note, hledger uses banker’s rounding: it-rounds to the nearest even number, eg 0.5 displayed with zero decimal-places is "0").---File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal--10.13 Costs-===========--After a posting amount, you can note its cost (when buying) or selling-price (when selling) in another commodity, by writing either ‘@-UNITPRICE’ or ‘@@ TOTALPRICE’ after it. This indicates a conversion-transaction, where one commodity is exchanged for another.-- (You might also see this called "transaction price" in hledger docs,-discussions, or code; that term was directionally neutral and reminded-that it is a price specific to a transaction, but we now just call it-"cost", with the understanding that the transaction could be a purchase-or a sale.)-- Costs are usually written explicitly with ‘@’ or ‘@@’, but can also-be inferred automatically for simple multi-commodity transactions.-Note, if costs are inferred, the order of postings is significant; the-first posting will have a cost attached, in the commodity of the second.-- As an example, here are several ways to record purchases of a foreign-currency in hledger, using the cost notation either explicitly or-implicitly:-- 1. Write the price per unit, as ‘@ UNITPRICE’ after the amount:-- 2009/1/1- assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each- assets:dollars ; balancing amount is -$135.00-- 2. Write the total price, as ‘@@ TOTALPRICE’ after the amount:-- 2009/1/1- assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot- assets:dollars-- 3. Specify amounts for all postings, using exactly two commodities,- and let hledger infer the price that balances the transaction.- Note the effect of posting order: the price is added to first- posting, making it ‘€100 @@ $135’, as in example 2:-- 2009/1/1- assets:euros €100 ; one hundred euros purchased- assets:dollars $-135 ; for $135-- Amounts can be converted to cost at report time using the ‘-B/--cost’-flag; this is discussed more in the ˜COST REPORTING section.--* Menu:--* Other cost/lot notations::---File: hledger.info, Node: Other cost/lot notations, Up: Costs--10.13.1 Other cost/lot notations-----------------------------------A slight digression for Ledger and Beancount users. Ledger has a number-of cost/lot-related notations:-- • ‘@ UNITCOST’ and ‘@@ TOTALCOST’- • expresses a conversion rate, as in hledger- • when buying, also creates a lot than can be selected at- selling time-- • ‘(@) UNITCOST’ and ‘(@@) TOTALCOST’ (virtual cost)- • like the above, but also means "this cost was exceptional,- don’t use it when inferring market prices".-- Currently, hledger treats the above like ‘@’ and ‘@@’; the-parentheses are ignored.-- • ‘{=FIXEDUNITCOST}’ and ‘{{=FIXEDTOTALCOST}}’ (fixed price)- • when buying, means "this cost is also the fixed price, don’t- let it fluctuate in value reports"-- • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ (lot price)- • can be used identically to ‘@ UNITCOST’ and ‘@@ TOTALCOST’,- also creates a lot- • when selling, combined with ‘@ ...’, specifies an investment- lot by its cost basis; does not check if that lot is present-- • and related: ‘[YYYY/MM/DD]’ (lot date)- • when buying, attaches this acquisition date to the lot- • when selling, selects a lot by its acquisition date-- • ‘(SOME TEXT)’ (lot note)- • when buying, attaches this note to the lot- • when selling, selects a lot by its note-- Currently, hledger accepts any or all of the above in any order after-the posting amount, but ignores them. (This can break transaction-balancing.)-- For Beancount users, the notation and behaviour is different:-- • ‘@ UNITCOST’ and ‘@@ TOTALCOST’- • expresses a cost without creating a lot, as in hledger- • when buying (augmenting) or selling (reducing) a lot, combined- with ‘{...}’: documents the cost/selling price (not used for- transaction balancing)-- • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’- • when buying (augmenting), expresses the cost for transaction- balancing, and also creates a lot with this cost basis- attached- • when selling (reducing),- • selects a lot by its cost basis- • raises an error if that lot is not present or can not be- selected unambiguously (depending on booking method- configured)- • expresses the selling price for transaction balancing-- Currently, hledger accepts the ‘{UNITCOST}’/‘{{TOTALCOST}}’ notation-but ignores it.-- • variations: ‘{}’, ‘{YYYY-MM-DD}’, ‘{"LABEL"}’, ‘{UNITCOST,- "LABEL"}’, ‘{UNITCOST, YYYY-MM-DD, "LABEL"}’ etc.-- Currently, hledger rejects these.---File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal--10.14 Balance assertions-========================--hledger supports Ledger-style balance assertions in journal files.-These look like, for example, ‘= EXPECTEDBALANCE’ following a posting’s-amount. Eg here we assert the expected dollar balance in accounts a and-b after each posting:--2013/1/1- a $1 =$1- b =$-1--2013/1/2- a $1 =$2- b $-1 =$-2-- After reading a journal file, hledger will check all balance-assertions and report an error if any of them fail. Balance assertions-can protect you from, eg, inadvertently disrupting reconciled balances-while cleaning up old entries. You can disable them temporarily with-the ‘-I/--ignore-assertions’ flag, which can be useful for-troubleshooting or for reading Ledger files. (Note: this flag currently-does not disable balance assignments, described below).--* Menu:--* Assertions and ordering::-* Assertions and multiple included files::-* Assertions and multiple -f files::-* Assertions and commodities::-* Assertions and prices::-* Assertions and subaccounts::-* Assertions and virtual postings::-* Assertions and auto postings::-* Assertions and precision::---File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions--10.14.1 Assertions and ordering----------------------------------hledger sorts an account’s postings and assertions first by date and-then (for postings on the same day) by parse order. Note this is-different from Ledger, which sorts assertions only by parse order.-(Also, Ledger assertions do not see the accumulated effect of repeated-postings to the same account within a transaction.)-- So, hledger balance assertions keep working if you reorder-differently-dated transactions within the journal. But if you reorder-same-dated transactions or postings, assertions might break and require-updating. This order dependence does bring an advantage: precise-control over the order of postings and assertions within a day, so you-can assert intra-day balances.---File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions--10.14.2 Assertions and multiple included files-------------------------------------------------Multiple files included with the ‘include’ directive are processed as if-concatenated into one file, preserving their order and the posting order-within each file. It means that balance assertions in later files will-see balance from earlier files.-- And if you have multiple postings to an account on the same day,-split across multiple files, and you want to assert the account’s-balance on that day, you’ll need to put the assertion in the right file-- the last one in the sequence, probably.---File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions--10.14.3 Assertions and multiple -f files-------------------------------------------Unlike ‘include’, when multiple files are specified on the command line-with multiple ‘-f/--file’ options, balance assertions will not see-balance from earlier files. This can be useful when you do not want-problems in earlier files to disrupt valid assertions in later files.-- If you do want assertions to see balance from earlier files, use-‘include’, or concatenate the files temporarily.---File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions--10.14.4 Assertions and commodities-------------------------------------The asserted balance must be a simple single-commodity amount, and in-fact the assertion checks only this commodity’s balance within the-(possibly multi-commodity) account balance. This is how assertions work-in Ledger also. We could call this a "partial" balance assertion.-- To assert the balance of more than one commodity in an account, you-can write multiple postings, each asserting one commodity’s balance.-- You can make a stronger "total" balance assertion by writing a double-equals sign (‘== EXPECTEDBALANCE’). This asserts that there are no-other commodities in the account besides the asserted one (or at least,-that their balance is 0).--2013/1/1- a $1- a 1€- b $-1- c -1€--2013/1/2 ; These assertions succeed- a 0 = $1- a 0 = 1€- b 0 == $-1- c 0 == -1€--2013/1/3 ; This assertion fails as 'a' also contains 1€- a 0 == $1-- It’s not yet possible to make a complete assertion about a balance-that has multiple commodities. One workaround is to isolate each-commodity into its own subaccount:--2013/1/1- a:usd $1- a:euro 1€- b--2013/1/2- a 0 == 0- a:usd 0 == $1- a:euro 0 == 1€---File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions--10.14.5 Assertions and prices--------------------------------Balance assertions ignore costs, and should normally be written without-one:--2019/1/1- (a) $1 @ €1 = $1-- We do allow prices to be written there, however, and print shows-them, even though they don’t affect whether the assertion passes or-fails. This is for backward compatibility (hledger’s close command used-to generate balance assertions with prices), and because balance-_assignments_ do use them (see below).---File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions--10.14.6 Assertions and subaccounts-------------------------------------The balance assertions above (‘=’ and ‘==’) do not count the balance-from subaccounts; they check the account’s exclusive balance only. You-can assert the balance including subaccounts by writing ‘=*’ or ‘==*’,-eg:--2019/1/1- equity:opening balances- checking:a 5- checking:b 5- checking 1 ==* 11---File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions--10.14.7 Assertions and virtual postings------------------------------------------Balance assertions always consider both real and virtual postings; they-are not affected by the ‘--real/-R’ flag or ‘real:’ query.---File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions--10.14.8 Assertions and auto postings---------------------------------------Balance assertions _are_ affected by the ‘--auto’ flag, which generates-auto postings, which can alter account balances. Because auto postings-are optional in hledger, accounts affected by them effectively have two-balances. But balance assertions can only test one or the other of-these. So to avoid making fragile assertions, either:-- • assert the balance calculated with ‘--auto’, and always use- ‘--auto’ with that file- • or assert the balance calculated without ‘--auto’, and never use- ‘--auto’ with that file- • or avoid balance assertions on accounts affected by auto postings- (or avoid auto postings entirely).---File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions--10.14.9 Assertions and precision-----------------------------------Balance assertions compare the exactly calculated amounts, which are not-always what is shown by reports. Eg a commodity directive may limit the-display precision, but this will not affect balance assertions. Balance-assertion failure messages show exact amounts.---File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal--10.15 Posting comments-======================--Text following ‘;’, at the end of a posting line, and/or on indented-lines immediately below it, form comments for that posting. They are-reproduced by ‘print’ but otherwise ignored, except they may contain-tags, which are not ignored.--2012-01-01- expenses 1 ; a comment for posting 1- assets- ; a comment for posting 2- ; a second comment line for posting 2---File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal--10.16 Tags-==========--Tags are a way to add extra labels or labelled data to transactions,-postings, or accounts, which you can then search or pivot on.-- They are written as a word (optionally hyphenated) immediately-followed by a full colon, in a transaction or posting or account-directive’s comment. (This is an exception to the usual rule that-things in comments are ignored.) Eg, here four different tags are-recorded: one on the checking account, two on the transaction, and one-on the expenses posting:--account assets:checking ; accounttag:--2017/1/16 bought groceries ; transactiontag-1:- ; transactiontag-2:- assets:checking $-1- expenses:food $1 ; postingtag:-- Postings also inherit tags from their transaction and their account.-And transactions also acquire tags from their postings (and postings’-accounts). So in the example above, the expenses posting effectively-has all four tags (by inheriting from account and transaction), and the-transaction also has all four tags (by acquiring from the expenses-posting).-- You can list tag names with ‘hledger tags [NAMEREGEX]’, or match by-tag name with a ‘tag:NAMEREGEX’ query.--* Menu:--* Tag values::---File: hledger.info, Node: Tag values, Up: Tags--10.16.1 Tag values---------------------Tags can have a value, which is any text after the colon up until a-comma or end of line (with surrounding whitespace removed). Note this-means that hledger tag values can not contain commas. Eg in the-following posting, the three tags’ values are "value 1", "value 2", and-"" (empty) respectively:-- expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz-- Note that tags can be repeated, and are additive rather than-overriding: when the same tag name is seen again with a new value, the-new name:value pair is added to the tags. (It is not possible to-override a tag’s value or remove a tag.)-- You can list a tag’s values with ‘hledger tags TAGNAME --values’, or-match by tag value with a ‘tag:NAMEREGEX=VALUEREGEX’ query.---File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal--10.17 Directives-================--A directive is a line in the journal beginning with a special keyword,-that influences how the journal is processed, how things are displayed,-and so on. hledger’s directives are based on (a subset of) Ledger’s,-but there are many differences, and also some differences between-hledger versions. Here are some more definitions:-- • _subdirective_ - Some directives support subdirectives, written- indented below the parent directive.-- • _decimal mark_ - The character to interpret as a decimal mark- (period or comma) when parsing amounts of a commodity.-- • _display style_ - How to display amounts of a commodity in output:- symbol side and spacing, digit groups, decimal mark, and number of- decimal places.-- Directives are not required when starting out with hledger, but you-will probably want to add some as your needs grow. Here some key-directives for particular needs:--purpose directives----------------------------------------------------------------------------*READING DATA:*-Declare file’s decimal mark to help parse ‘decimal-mark’-amounts accurately-Rewrite account names ‘alias’-Comment out sections of the data ‘comment’-Include extra data files ‘include’-*GENERATING DATA:*-Generate recurring transactions or budget ‘~’-goals-Generate extra postings on transactions ‘=’-*CHECKING FOR ERRORS:*-Define valid entities to provide more ‘account’, ‘commodity’,-error checking ‘payee’-*REPORTING:*-Declare accounts’ type and display order ‘account’-Declare commodity display styles ‘commodity’-Declare market prices ‘P’--* Menu:--* Directive effects::-* Directives and multiple files::---File: hledger.info, Node: Directive effects, Next: Directives and multiple files, Up: Directives--10.17.1 Directive effects----------------------------And here is what each directive does, and which files and journal-entries (transactions) it affects:--directivewhat it does ends- at- file- end?-----------------------------------------------------------------------------*‘account’*Declares an account, for checking all entries in all files; andN- its display order and type. Subdirectives: any text, ignored.-*‘alias’*Rewrites account names, in following entries until end of Y- current file or ‘end aliases’. Command line equivalent:- ‘--alias’-*‘comment’*Ignores part of the journal file, until end of current file orY- ‘end comment’.-*‘commodity’*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N- all amounts in all files 2. the decimal mark for parsing- amounts of this commodity, in the following entries until end of- current file (if there is no ‘decimal-mark’ directive) 3. and- the display style for amounts of this commodity 4. which is- also the precision to use for balanced-transaction checking in- this commodity. Takes precedence over ‘D’. Subdirectives:- ‘format’ (Ledger-compatible syntax). Command line equivalent:- ‘-c/--commodity-style’-*‘decimal-mark’*Declares the decimal mark, for parsing amounts of all Y- commodities in following entries until next ‘decimal-mark’ or- end of current file. Included files can override. Takes- precedence over ‘commodity’ and ‘D’.-*‘include’*Includes entries and directives from another file, as if theyN- were written inline. Command line alternative: multiple- ‘-f/--file’-*‘payee’*Declares a payee name, for checking all entries in all files. N-*‘P’*Declares the market price of a commodity on some date, for value N- reports.-*‘~’*Declares a periodic transaction rule that generates future N-(tilde)transactions with ‘--forecast’ and budget goals with ‘balance- --budget’.-Other-syntax:-*‘applyPrepends a common parent account to all account names, in Y-account’*following entries until end of current file or ‘end apply- account’.-*‘D’*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N- there is no ‘commodity’ directive for this commodity: its- decimal mark, balancing precision, and display style, as above.-*‘Y’*Sets a default year to use for any yearless dates, in following Y- entries until end of current file.-*‘=’*Declares an auto posting rule that generates extra postings on partly-(equals)matched transactions with ‘--auto’, in current, parent, and- child files (but not sibling files, see #1212).-*OtherOther directives from Ledger’s file format are accepted but-Ledgerignored.-directives*---File: hledger.info, Node: Directives and multiple files, Prev: Directive effects, Up: Directives--10.17.2 Directives and multiple files----------------------------------------If you use multiple ‘-f’/‘--file’ options, or the ‘include’ directive,-hledger will process multiple input files. But directives which affect-input typically have effect only until the end of the file in which they-occur (and on any included files in that region).-- This may seem inconvenient, but it’s intentional; it makes reports-stable and deterministic, independent of the order of input. Otherwise-you could see different numbers if you happened to write -f options in a-different order, or if you moved includes around while cleaning up your-files.-- It can be surprising though; for example, it means that ‘alias’-directives do not affect parent or sibling files (see below).---File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal--10.18 ‘account’ directive-=========================--‘account’ directives can be used to declare accounts (ie, the places-that amounts are transferred from and to). Though not required, these-declarations can provide several benefits:-- • They can document your intended chart of accounts, providing a- reference.- • In strict mode, they restrict which accounts may be posted to by- transactions, which helps detect typos.- • They control account display order in reports, allowing- non-alphabetic sorting (eg Revenues to appear above Expenses).- • They help with account name completion (in hledger add,- hledger-web, hledger-iadd, ledger-mode, etc.)- • They can store additional account information as comments, or as- tags which can be used to filter or pivot reports.- • They can help hledger know your accounts’ types (asset, liability,- equity, revenue, expense), affecting reports like balancesheet and- incomestatement.-- They are written as the word ‘account’ followed by a hledger-style-account name, eg:--account assets:bank:checking-- Note, however, that accounts declared in account directives are not-allowed to have surrounding brackets and parentheses, unlike accounts-used in postings. So the following journal will not parse:--account (assets:bank:checking)--* Menu:--* Account comments::-* Account subdirectives::-* Account error checking::-* Account display order::-* Account types::---File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive--10.18.1 Account comments---------------------------Text following *two or more spaces* and ‘;’ at the end of an account-directive line, and/or following ‘;’ on indented lines immediately below-it, form comments for that account. They are ignored except they may-contain tags, which are not ignored.-- The two-space requirement for same-line account comments is because-‘;’ is allowed in account names.--account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon- ; next-line comment- ; some tags - type:A, acctnum:12345---File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive--10.18.2 Account subdirectives--------------------------------Ledger-style indented subdirectives are also accepted, but currently-ignored:--account assets:bank:checking- format subdirective is ignored---File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive--10.18.3 Account error checking---------------------------------By default, accounts need not be declared; they come into existence when-a posting references them. This is convenient, but it means hledger-can’t warn you when you mis-spell an account name in the journal.-Usually you’ll find that error later, as an extra account in balance-reports, or an incorrect balance when reconciling.-- In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will-report an error if any transaction uses an account name that has not-been declared by an account directive. Some notes:-- • The declaration is case-sensitive; transactions must use the- correct account name capitalisation.- • The account directive’s scope is "whole file and below" (see- directives). This means it affects all of the current file, and- any files it includes, but not parent or sibling files. The- position of account directives within the file does not matter,- though it’s usual to put them at the top.- • Accounts can only be declared in ‘journal’ files, but will affect- included files of all types.- • It’s currently not possible to declare "all possible subaccounts"- with a wildcard; every account posted to must be declared.---File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive--10.18.4 Account display order--------------------------------The order in which account directives are written influences the order-in which accounts appear in reports, hledger-ui, hledger-web etc. By-default accounts appear in alphabetical order, but if you add these-account directives to the journal file:--account assets-account liabilities-account equity-account revenues-account expenses-- those accounts will be displayed in declaration order:--$ hledger accounts -1-assets-liabilities-equity-revenues-expenses-- Any undeclared accounts are displayed last, in alphabetical order.-- Sorting is done at each level of the account tree, within each group-of sibling accounts under the same parent. And currently, this-directive:--account other:zoo-- would influence the position of ‘zoo’ among ‘other’’s subaccounts,-but not the position of ‘other’ among the top-level accounts. This-means:-- • you will sometimes declare parent accounts (eg ‘account other’- above) that you don’t intend to post to, just to customize their- display order- • sibling accounts stay together (you couldn’t display ‘x:y’ in- between ‘a:b’ and ‘a:c’).---File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive--10.18.5 Account types------------------------hledger knows that accounts come in several types: assets, liabilities,-expenses and so on. This enables easy reports like balancesheet and-incomestatement, and filtering by account type with the ‘type:’ query.-- As a convenience, hledger will detect these account types-automatically if you are using common english-language top-level account-names (described below). But generally we recommend you declare types-explicitly, by adding a ‘type:’ tag to your top-level account-directives. Subaccounts will inherit the type of their parent. The-tag’s value should be one of the five main account types:-- • ‘A’ or ‘Asset’ (things you own)- • ‘L’ or ‘Liability’ (things you owe)- • ‘E’ or ‘Equity’ (investment/ownership; balanced counterpart of- assets & liabilities)- • ‘R’ or ‘Revenue’ (what you received money from, AKA income;- technically part of Equity)- • ‘X’ or ‘Expense’ (what you spend money on; technically part of- Equity)-- or, it can be (these are used less often):-- • ‘C’ or ‘Cash’ (a subtype of Asset, indicating liquid assets for the- cashflow report)- • ‘V’ or ‘Conversion’ (a subtype of Equity, for conversions (see COST- REPORTING).)-- Here is a typical set of account type declarations:--account assets ; type: A-account liabilities ; type: L-account equity ; type: E-account revenues ; type: R-account expenses ; type: X--account assets:bank ; type: C-account assets:cash ; type: C--account equity:conversion ; type: V-- Here are some tips for working with account types.-- • The rules for inferring types from account names are as follows.- These are just a convenience that sometimes help new users get- going; if they don’t work for you, just ignore them and declare- your account types. See also Regular expressions.-- If account's name contains this (CI) regular expression: | its type is:- --------------------------------------------------------------------|-------------- ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash- ^assets?(:|$) | Asset- ^(debts?|liabilit(y|ies))(:|$) | Liability- ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion- ^equity(:|$) | Equity- ^(income|revenue)s?(:|$) | Revenue- ^expenses?(:|$) | Expense-- • If you declare any account types, it’s a good idea to declare an- account for all of the account types, because a mixture of declared- and name-inferred types can disrupt certain reports.-- • Certain uses of account aliases can disrupt account types. See- Rewriting accounts > Aliases and account types.-- • As mentioned above, subaccounts will inherit a type from their- parent account. More precisely, an account’s type is decided by- the first of these that exists:-- 1. A ‘type:’ declaration for this account.- 2. A ‘type:’ declaration in the parent accounts above it,- preferring the nearest.- 3. An account type inferred from this account’s name.- 4. An account type inferred from a parent account’s name,- preferring the nearest parent.- 5. Otherwise, it will have no type.-- • For troubleshooting, you can list accounts and their types with:-- $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]---File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal--10.19 ‘alias’ directive-=======================--You can define account alias rules which rewrite your account names, or-parts of them, before generating reports. This can be useful for:-- • expanding shorthand account names to their full form, allowing- easier data entry and a less verbose journal- • adapting old journals to your current chart of accounts- • experimenting with new account organisations, like a new hierarchy- • combining two accounts into one, eg to see their sum or difference- on one line- • customising reports-- Account aliases also rewrite account names in account directives.-They do not affect account names being entered via hledger add or-hledger-web.-- Account aliases are very powerful. They are generally easy to use-correctly, but you can also generate invalid account names with them;-more on this below.-- See also Rewrite account names.--* Menu:--* Basic aliases::-* Regex aliases::-* Combining aliases::-* Aliases and multiple files::-* end aliases directive::-* Aliases can generate bad account names::-* Aliases and account types::---File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive--10.19.1 Basic aliases------------------------To set an account alias, use the ‘alias’ directive in your journal file.-This affects all subsequent journal entries in the current file or its-included files (but note: not sibling or parent files). The spaces-around the = are optional:--alias OLD = NEW-- Or, you can use the ‘--alias 'OLD=NEW'’ option on the command line.-This affects all entries. It’s useful for trying out aliases-interactively.-- OLD and NEW are case sensitive full account names. hledger will-replace any occurrence of the old account name with the new one.-Subaccounts are also affected. Eg:--alias checking = assets:bank:wells fargo:checking-; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"---File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive--10.19.2 Regex aliases------------------------There is also a more powerful variant that uses a regular expression,-indicated by wrapping the pattern in forward slashes. (This is the only-place where hledger requires forward slashes around a regular-expression.)-- Eg:--alias /REGEX/ = REPLACEMENT-- or:--$ hledger --alias '/REGEX/=REPLACEMENT' ...-- Any part of an account name matched by REGEX will be replaced by-REPLACEMENT. REGEX is case-insensitive as usual.-- If you need to match a forward slash, escape it with a backslash, eg-‘/\/=:’.-- If REGEX contains parenthesised match groups, these can be referenced-by the usual backslash and number in REPLACEMENT:--alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3-; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"-- REPLACEMENT continues to the end of line (or on command line, to end-of option argument), so it can contain trailing whitespace.---File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive--10.19.3 Combining aliases----------------------------You can define as many aliases as you like, using journal directives-and/or command line options.-- Recursive aliases - where an account name is rewritten by one alias,-then by another alias, and so on - are allowed. Each alias sees the-effect of previously applied aliases.-- In such cases it can be important to understand which aliases will be-applied and in which order. For (each account name in) each journal-entry, we apply:-- 1. ‘alias’ directives preceding the journal entry, most recently- parsed first (ie, reading upward from the journal entry, bottom to- top)- 2. ‘--alias’ options, in the order they appeared on the command line- (left to right).-- In other words, for (an account name in) a given journal entry:-- • the nearest alias declaration before/above the entry is applied- first- • the next alias before/above that will be be applied next, and so on- • aliases defined after/below the entry do not affect it.-- This gives nearby aliases precedence over distant ones, and helps-provide semantic stability - aliases will keep working the same way-independent of which files are being read and in which order.-- In case of trouble, adding ‘--debug=6’ to the command line will show-which aliases are being applied when.---File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive--10.19.4 Aliases and multiple files-------------------------------------As explained at Directives and multiple files, ‘alias’ directives do not-affect parent or sibling files. Eg in this command,--hledger -f a.aliases -f b.journal-- account aliases defined in a.aliases will not affect b.journal.-Including the aliases doesn’t work either:--include a.aliases--2020-01-01 ; not affected by a.aliases- foo 1- bar-- This means that account aliases should usually be declared at the-start of your top-most file, like this:--alias foo=Foo-alias bar=Bar--2020-01-01 ; affected by aliases above- foo 1- bar--include c.journal ; also affected---File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive--10.19.5 ‘end aliases’ directive----------------------------------You can clear (forget) all currently defined aliases (seen in the-journal so far, or defined on the command line) with this directive:--end aliases---File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive--10.19.6 Aliases can generate bad account names-------------------------------------------------Be aware that account aliases can produce malformed account names, which-could cause confusing reports or invalid ‘print’ output. For example,-you could erase all account names:--2021-01-01- a:aa 1- b--$ hledger print --alias '/.*/='-2021-01-01- 1-- The above ‘print’ output is not a valid journal. Or you could insert-an illegal double space, causing ‘print’ output that would give a-different journal when reparsed:--2021-01-01- old 1- other--$ hledger print --alias old="new USD" | hledger -f- print-2021-01-01- new USD 1- other---File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive--10.19.7 Aliases and account types------------------------------------If an account with a type declaration (see Declaring accounts > Account-types) is renamed by an alias, normally the account type remains in-effect.-- However, renaming in a way that reshapes the account tree (eg-renaming parent accounts but not their children, or vice versa) could-prevent child accounts from inheriting the account type of their-parents.-- Secondly, if an account’s type is being inferred from its name,-renaming it by an alias could prevent or alter that.-- If you are using account aliases and the ‘type:’ query is not-matching accounts as you expect, try troubleshooting with the accounts-command, eg something like:--$ hledger accounts --alias assets=bassetts type:a---File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal--10.20 ‘commodity’ directive-===========================--You can use ‘commodity’ directives to declare your commodities. In fact-the ‘commodity’ directive performs several functions at once:-- 1. It declares commodities which may be used in the journal. This can- optionally be enforced, providing useful error checking. (Cf- Commodity error checking)-- 2. It declares which decimal mark character (period or comma), to- expect when parsing input - useful to disambiguate international- number formats in your data. Without this, hledger will parse both- ‘1,000’ and ‘1.000’ as 1. (Cf Amounts)-- 3. It declares how to render the commodity’s amounts when displaying- output - the decimal mark, any digit group marks, the number of- decimal places, symbol placement and so on. (Cf Commodity display- style)-- You will run into one of the problems solved by commodity directives-sooner or later, so we recommend using them, for robust and predictable-parsing and display.-- Generally you should put them at the top of your journal file (since-for function 2, they affect only following amounts, cf #793).-- A commodity directive is just the word ‘commodity’ followed by a-sample amount, like this:--;commodity SAMPLEAMOUNT--commodity $1000.00-commodity 1,000.0000 AAAA ; optional same-line comment-- It may also be written on multiple lines, and use the ‘format’-subdirective, as in Ledger. Note in this case the commodity symbol-appears twice; it must be the same in both places:--;commodity SYMBOL-; format SAMPLEAMOUNT--; display indian rupees with currency name on the left,-; thousands, lakhs and crores comma-separated,-; period as decimal point, and two decimal places.-commodity INR- format INR 1,00,00,000.00-- Other indented subdirectives are currently ignored.-- Remember that if the commodity symbol contains spaces, numbers, or-punctuation, it must be enclosed in double quotes (cf Commodity).-- The amount’s quantity does not matter; only the format is-significant. It must include a decimal mark - either a period or a-comma - followed by 0 or more decimal digits.-- A few more examples:--# number formats for $, EUR, INR and the no-symbol commodity:-commodity $1,000.00-commodity EUR 1.000,00-commodity INR 9,99,99,999.0-commodity 1 000 000.-- Note hledger normally uses banker’s rounding, so 0.5 displayed with-zero decimal digits is "0". (More at Commodity display style.)-- Even in the presence of commodity directives, the commodity display-style can still be overridden by supplying a command line option.--* Menu:--* Commodity error checking::---File: hledger.info, Node: Commodity error checking, Up: commodity directive--10.20.1 Commodity error checking-----------------------------------In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will-report an error if a commodity symbol is used that has not been declared-by a ‘commodity’ directive. This works similarly to account error-checking, see the notes there for more details.-- Note, this disallows amounts without a commodity symbol, because-currently it’s not possible (?) to declare the "no-symbol" commodity-with a directive. This is one exception for convenience: zero amounts-are always allowed to have no commodity symbol.---File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal--10.21 ‘decimal-mark’ directive-==============================--You can use a ‘decimal-mark’ directive - usually one per file, at the-top of the file - to declare which character represents a decimal mark-when parsing amounts in this file. It can look like--decimal-mark .-- or--decimal-mark ,-- This prevents any ambiguity when parsing numbers in the file, so we-recommend it, especially if the file contains digit group marks (eg-thousands separators).---File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal--10.22 ‘include’ directive-=========================--You can pull in the content of additional files by writing an include-directive, like this:--include FILEPATH-- Only journal files can include, and only journal, timeclock or-timedot files can be included (not CSV files, currently).-- If the file path does not begin with a slash, it is relative to the-current file’s folder.-- A tilde means home directory, eg: ‘include ~/main.journal’.-- The path may contain glob patterns to match multiple files, eg:-‘include *.journal’.-- There is limited support for recursive wildcards: ‘**/’ (the slash is-required) matches 0 or more subdirectories. It’s not super convenient-since you have to avoid include cycles and including directories, but-this can be done, eg: ‘include */**/*.journal’.-- The path may also be prefixed to force a specific file format,-overriding the file extension (as described in hledger.1 -> Input-files): ‘include timedot:~/notes/2020*.md’.---File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal--10.23 ‘P’ directive-===================--The ‘P’ directive declares a market price, which is a conversion rate-between two commodities on a certain date. This allows value reports to-convert amounts of one commodity to their value in another, on or after-that date. These prices are often obtained from a stock exchange,-cryptocurrency exchange, the or foreign exchange market.-- The format is:--P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT-- DATE is a simple date, COMMODITY1SYMBOL is the symbol of the-commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and-quantity) of commodity 2 that one unit of commodity 1 is worth on this-date. Examples:--# one euro was worth $1.35 from 2009-01-01 onward:-P 2009-01-01 € $1.35--# and $1.40 from 2010-01-01 onward:-P 2010-01-01 € $1.40-- The ‘-V’, ‘-X’ and ‘--value’ flags use these market prices to show-amount values in another commodity. See Valuation.---File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal--10.24 ‘payee’ directive-=======================--‘payee PAYEE NAME’-- This directive can be used to declare a limited set of payees which-may appear in transaction descriptions. The "payees" check will report-an error if any transaction refers to a payee that has not been-declared. Eg:--payee Whole Foods-- Any indented subdirectives are currently ignored.---File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal--10.25 ‘tag’ directive-=====================--‘tag TAGNAME’-- This directive can be used to declare a limited set of tag names-allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg:--tag item-id-- Any indented subdirectives are currently ignored.-- The "tags" check will report an error if any undeclared tag name is-used. It is quite easy to accidentally create a tag through normal use-of colons in comments(#comments]; if you want to prevent this, you can-declare and check your tags .---File: hledger.info, Node: Periodic transactions, Next: Other syntax, Prev: tag directive, Up: Journal--10.26 Periodic transactions-===========================--The ‘~’ directive declares recurring transactions. Such directives-allow hledger to generate temporary future transactions (visible in-reports, not in the journal file) to help with forecasting or budgeting.-- Periodic transactions can be a little tricky, so before you use them,-read this whole section, or at least these tips:-- 1. Two spaces accidentally added or omitted will cause you trouble -- read about this below.- 2. For troubleshooting, show the generated transactions with ‘hledger- print --forecast tag:generated’ or ‘hledger register --forecast- tag:generated’.- 3. Forecasted transactions will begin only after the last- non-forecasted transaction’s date.- 4. Forecasted transactions will end 6 months from today, by default.- See below for the exact start/end rules.- 5. period expressions can be tricky. Their documentation needs- improvement, but is worth studying.- 6. Some period expressions with a repeating interval must begin on a- natural boundary of that interval. Eg in ‘weekly from DATE’, DATE- must be a monday. ‘~ weekly from 2019/10/1’ (a tuesday) will give- an error.- 7. Other period expressions with an interval are automatically- expanded to cover a whole number of that interval. (This is done- to improve reports, but it also affects periodic transactions.- Yes, it’s a bit inconsistent with the above.) Eg: ‘~ every 10th- day of month from 2020/01’, which is equivalent to ‘~ every 10th- day of month from 2020/01/01’, will be adjusted to start on- 2019/12/10.--* Menu:--* Periodic rule syntax::-* Periodic rules and relative dates::-* Two spaces between period expression and description!::---File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions--10.26.1 Periodic rule syntax-------------------------------A periodic transaction rule looks like a normal journal entry, with the-date replaced by a tilde (‘~’) followed by a period expression-(mnemonic: ‘~’ looks like a recurring sine wave.):--# every first of month-~ monthly- expenses:rent $2000- assets:bank:checking--# every 15th of month in 2023's first quarter:-~ monthly from 2023-04-15 to 2023-06-16- expenses:utilities $400- assets:bank:checking-- The period expression is the same syntax used for specifying-multi-period reports, just interpreted differently; there, it specifies-report periods; here it specifies recurrence dates (the periods’ start-dates).---File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions--10.26.2 Periodic rules and relative dates--------------------------------------------Partial or relative dates (like ‘12/31’, ‘25’, ‘tomorrow’, ‘last week’,-‘next quarter’) are usually not recommended in periodic rules, since the-results will change as time passes. If used, they will be interpreted-relative to, in order of preference:-- 1. the first day of the default year specified by a recent ‘Y’- directive- 2. or the date specified with ‘--today’- 3. or the date on which you are running the report.-- They will not be affected at all by report period or forecast period-dates.---File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions--10.26.3 Two spaces between period expression and description!----------------------------------------------------------------If the period expression is followed by a transaction description, these-must be separated by *two or more spaces*. This helps hledger know-where the period expression ends, so that descriptions can not-accidentally alter their meaning, as in this example:--; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"-; ||-; vv-~ every 2 months in 2020, we will review- assets:bank:checking $1500- income:acme inc-- So,-- • Do write two spaces between your period expression and your- transaction description, if any.- • Don’t accidentally write two spaces in the middle of your period- expression.---File: hledger.info, Node: Other syntax, Prev: Periodic transactions, Up: Journal--10.27 Other syntax-==================--hledger journal format supports quite a few other features, mainly to-make interoperating with or converting from Ledger easier. Note some of-the features below are powerful and can be useful in special cases, but-in general, features in this section are considered less important or-even not recommended for most users. Downsides are mentioned to help-you decide if you want to use them.--* Menu:--* Auto postings::-* Balance assignments::-* Bracketed posting dates::-* D directive::-* apply account directive::-* Y directive::-* Secondary dates::-* Star comments::-* Valuation expressions::-* Virtual postings::-* Other Ledger directives::---File: hledger.info, Node: Auto postings, Next: Balance assignments, Up: Other syntax--10.27.1 Auto postings------------------------The ‘=’ directive declares a rule for automatically adding temporary-extra postings (visible in reports, not in the journal file) to all-transactions matched by a certain query, when you use the ‘--auto’ flag.-- Downsides: depending on generated data for your reports makes your-financial data less portable, less future-proof, and less trustworthy in-an audit. Also, because the feature is optional, other features like-balance assertions can break depending on whether it is on or off.-- An auto posting rule looks a bit like a transaction:--= QUERY- ACCOUNT AMOUNT- ...- ACCOUNT [AMOUNT]-- except the first line is an equals sign (mnemonic: ‘=’ suggests-matching), followed by a query (which matches existing postings), and-each "posting" line describes a posting to be generated, and the posting-amounts can be:-- • a normal amount with a commodity symbol, eg ‘$2’. This will be- used as-is.- • a number, eg ‘2’. The commodity symbol (if any) from the matched- posting will be added to this.- • a numeric multiplier, eg ‘*2’ (a star followed by a number N). The- matched posting’s amount (and total price, if any) will be- multiplied by N.- • a multiplier with a commodity symbol, eg ‘*$2’ (a star, number N,- and symbol S). The matched posting’s amount will be multiplied by- N, and its commodity symbol will be replaced with S.-- Any query term containing spaces must be enclosed in single or double-quotes, as on the command line. Eg, note the quotes around the second-query term below:--= expenses:groceries 'expenses:dining out'- (budget:funds:dining out) *-1-- Some examples:--; every time I buy food, schedule a dollar donation-= expenses:food- (liabilities:charity) $-1--; when I buy a gift, also deduct that amount from a budget envelope subaccount-= expenses:gifts- assets:checking:gifts *-1- assets:checking *1--2017/12/1- expenses:food $10- assets:checking--2017/12/14- expenses:gifts $20- assets:checking--$ hledger print --auto-2017-12-01- expenses:food $10- assets:checking- (liabilities:charity) $-1--2017-12-14- expenses:gifts $20- assets:checking- assets:checking:gifts -$20- assets:checking $20--* Menu:--* Auto postings and multiple files::-* Auto postings and dates::-* Auto postings and transaction balancing / inferred amounts / balance assertions::-* Auto posting tags::---File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings--10.27.1.1 Auto postings and multiple files-..........................................--An auto posting rule can affect any transaction in the current file, or-in any parent file or child file. Note, currently it will not affect-sibling files (when multiple ‘-f’/‘--file’ are used - see #1212).---File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings--10.27.1.2 Auto postings and dates-.................................--A posting date (or secondary date) in the matched posting, or (taking-precedence) a posting date in the auto posting rule itself, will also be-used in the generated posting.---File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings--10.27.1.3 Auto postings and transaction balancing / inferred-............................................................--amounts / balance assertions Currently, auto postings are added:-- • after missing amounts are inferred, and transactions are checked- for balancedness,- • but before balance assertions are checked.-- Note this means that journal entries must be balanced both before and-after auto postings are added. This changed in hledger 1.12+; see #893-for background.-- This also means that you cannot have more than one auto-posting with-a missing amount applied to a given transaction, as it will be unable to-infer amounts.---File: hledger.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings--10.27.1.4 Auto posting tags-...........................--Automated postings will have some extra tags:-- • ‘generated-posting:= QUERY’ - shows this was generated by an auto- posting rule, and the query- • ‘_generated-posting:= QUERY’ - a hidden tag, which does not appear- in hledger’s output. This can be used to match postings generated- "just now", rather than generated in the past and saved to the- journal.-- Also, any transaction that has been changed by auto posting rules-will have these tags added:-- • ‘modified:’ - this transaction was modified- • ‘_modified:’ - a hidden tag not appearing in the comment; this- transaction was modified "just now".---File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Prev: Auto postings, Up: Other syntax--10.27.2 Balance assignments------------------------------Ledger-style balance assignments are also supported. These are like-balance assertions, but with no posting amount on the left side of the-equals sign; instead it is calculated automatically so as to satisfy the-assertion. This can be a convenience during data entry, eg when setting-opening balances:--; starting a new journal, set asset account balances-2016/1/1 opening balances- assets:checking = $409.32- assets:savings = $735.24- assets:cash = $42- equity:opening balances-- or when adjusting a balance to reality:--; no cash left; update balance, record any untracked spending as a generic expense-2016/1/15- assets:cash = $0- expenses:misc-- The calculated amount depends on the account’s balance in the-commodity at that point (which depends on the previously-dated postings-of the commodity to that account since the last balance assertion or-assignment).-- Downsides: using balance assignments makes your journal less-explicit; to know the exact amount posted, you have to run hledger or do-the calculations yourself, instead of just reading it. Also balance-assignments’ forcing of balances can hide errors. These things make-your financial data less portable, less future-proof, and less-trustworthy in an audit.--* Menu:--* Balance assignments and prices::---File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments--10.27.2.1 Balance assignments and prices-........................................--A cost in a balance assignment will cause the calculated amount to have-that price attached:--2019/1/1- (a) = $1 @ €2--$ hledger print --explicit-2019-01-01- (a) $1 @ €2 = $1 @ €2---File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax--10.27.3 Bracketed posting dates----------------------------------For setting posting dates and secondary posting dates, Ledger’s-bracketed date syntax is also supported: ‘[DATE]’, ‘[DATE=DATE2]’ or-‘[=DATE2]’ in posting comments. hledger will attempt to parse any-square-bracketed sequence of the ‘0123456789/-.=’ characters in this-way. With this syntax, DATE infers its year from the transaction and-DATE2 infers its year from DATE.-- Downsides: another syntax to learn, redundant with hledger’s-‘date:’/‘date2:’ tags, and confusingly similar to Ledger’s lot date-syntax.---File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax--10.27.4 ‘D’ directive------------------------‘D AMOUNT’-- This directive sets a default commodity, to be used for any-subsequent commodityless amounts (ie, plain numbers) seen while parsing-the journal. This effect lasts until the next ‘D’ directive, or the end-of the journal.-- For compatibility/historical reasons, ‘D’ also acts like a-‘commodity’ directive (setting the commodity’s decimal mark for parsing-and display style for output). So its argument is not just a commodity-symbol, but a full amount demonstrating the style. The amount must-include a decimal mark (either period or comma). Eg:--; commodity-less amounts should be treated as dollars-; (and displayed with the dollar sign on the left, thousands separators and two decimal places)-D $1,000.00--1/1- a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00- b-- Interactions with other directives:-- For setting a commodity’s display style, a ‘commodity’ directive has-highest priority, then a ‘D’ directive.-- For detecting a commodity’s decimal mark during parsing,-‘decimal-mark’ has highest priority, then ‘commodity’, then ‘D’.-- For checking commodity symbols with the check command, a ‘commodity’-directive is required (‘hledger check commodities’ ignores ‘D’-directives).-- Downsides: omitting commodity symbols makes your financial data less-explicit, less portable, and less trustworthy in an audit. It is-usually an unsustainable shortcut; sooner or later you will want to-track multiple commodities. D is overloaded with functions redundant-with ‘commodity’ and ‘decimal-mark’. And it works differently from-Ledger’s ‘D’.---File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax--10.27.5 ‘apply account’ directive------------------------------------This directive sets a default parent account, which will be prepended to-all accounts in following entries, until an ‘end apply account’-directive or end of current file. Eg:--apply account home--2010/1/1- food $10- cash--end apply account-- is equivalent to:--2010/01/01- home:food $10- home:cash $-10-- ‘account’ directives are also affected, and so is any ‘include’d-content.-- Account names entered via hledger add or hledger-web are not-affected.-- Account aliases, if any, are applied after the parent account is-prepended.-- Downsides: this can make your financial data less explicit, less-portable, and less trustworthy in an audit.---File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax--10.27.6 ‘Y’ directive------------------------‘Y YEAR’-- or (deprecated backward-compatible forms):-- ‘year YEAR’ ‘apply year YEAR’-- The space is optional. This sets a default year to be used for-subsequent dates which don’t specify a year. Eg:--Y2009 ; set default year to 2009--12/15 ; equivalent to 2009/12/15- expenses 1- assets--year 2010 ; change default year to 2010--2009/1/30 ; specifies the year, not affected- expenses 1- assets--1/31 ; equivalent to 2010/1/31- expenses 1- assets-- Downsides: omitting the year (from primary transaction dates, at-least) makes your financial data less explicit, less portable, and less-trustworthy in an audit. Such dates can get separated from their-corresponding Y directive, eg when evaluating a region of the journal in-your editor. A missing Y directive makes reports dependent on today’s-date.---File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax--10.27.7 Secondary dates--------------------------A secondary date is written after the primary date, following an equals-sign. If the year is omitted, the primary date’s year is assumed. When-running reports, the primary (left) date is used by default, but with-the ‘--date2’ flag (or ‘--aux-date’ or ‘--effective’), the secondary-(right) date will be used instead.-- The meaning of secondary dates is up to you, but it’s best to follow-a consistent rule. Eg "primary = the bank’s clearing date, secondary =-date the transaction was initiated, if different".-- Downsides: makes your financial data more complicated, less portable,-and less trustworthy in an audit. Keeping the meaning of the two dates-consistent requires discipline, and you have to remember which reporting-mode is appropriate for a given report. Posting dates are simpler and-better.---File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax--10.27.8 Star comments------------------------Lines beginning with ‘*’ (star/asterisk) are also comment lines. This-feature allows Emacs users to insert org headings in their journal,-allowing them to fold/unfold/navigate it like an outline when viewed-with org mode.-- Downsides: another, unconventional comment syntax to learn.-Decreases your journal’s portability. And switching to Emacs org mode-just for folding/unfolding meant losing the benefits of ledger mode;-nowadays you can add outshine mode to ledger mode to get folding without-losing ledger mode’s features.---File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax--10.27.9 Valuation expressions--------------------------------Ledger allows a valuation function or value to be written in double-parentheses after an amount. hledger ignores these.---File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax--10.27.10 Virtual postings----------------------------A posting with parentheses around the account name is called a _virtual-posting_ or _unbalanced posting_, which means it is exempt from the-usual rule that a transaction’s postings must balance add up to zero.-- This is not part of double entry bookkeeping, so you might choose to-avoid this feature. Or you can use it sparingly for certain special-cases where it can be convenient. Eg, you could set opening balances-without using a balancing equity account:--2022-01-01 opening balances- (assets:checking) $1000- (assets:savings) $2000-- A posting with brackets around the account name is called a _balanced-virtual posting_. The balanced virtual postings in a transaction must-add up to zero (separately from other postings). Eg:--2022-01-01 buy food with cash, update budget envelope subaccounts, & something else- assets:cash $-10 ; <- these balance each other- expenses:food $7 ; <-- expenses:food $3 ; <-- [assets:checking:budget:food] $-10 ; <- and these balance each other- [assets:checking:available] $10 ; <-- (something:else) $5 ; <- this is not required to balance-- Postings whose account names are neither parenthesised nor bracketed-are called _real postings_. You can exclude virtual postings from-reports with the ‘-R/--real’ flag or a ‘real:1’ query.-- Downsides: violates double entry bookkeeping, can be used to avoid-figuring out correct entries, makes your financial data less portable-and less trustworthy in an audit.---File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax--10.27.11 Other Ledger directives-----------------------------------These other Ledger directives are currently accepted but ignored. This-allows hledger to read more Ledger files, but be aware that hledger’s-reports may differ from Ledger’s if you use these.--apply fixed COMM AMT-apply tag TAG-assert EXPR-bucket / A ACCT-capture ACCT REGEX-check EXPR-define VAR=EXPR-end apply fixed-end apply tag-end apply year-end tag-eval / expr EXPR-python- PYTHONCODE-tag NAME-value EXPR---command-line-flags-- See also https://hledger.org/ledger.html for a detailed-hledger/Ledger syntax comparison.---File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top--11 CSV-******--hledger can read CSV files (Character Separated Value - usually comma,-semicolon, or tab) containing dated records, automatically converting-each record into a transaction.-- (To learn about _writing_ CSV, see CSV output.)-- For best error messages when reading CSV/TSV/SSV files, make sure-they have a corresponding ‘.csv’, ‘.tsv’ or ‘.ssv’ file extension or use-a hledger file prefix (see File Extension below).-- Each CSV file must be described by a corresponding _rules file_.-This contains rules describing the CSV data (header line, fields layout,-date format etc.), how to construct hledger transactions from it, and-how to categorise transactions based on description or other attributes.-- By default hledger looks for a rules file named like the CSV file-with an extra ‘.rules’ extension, in the same directory. Eg when asked-to read ‘foo/FILE.csv’, hledger looks for ‘foo/FILE.csv.rules’. You can-specify a different rules file with the ‘--rules-file’ option. If no-rules file is found, hledger will create a sample rules file, which-you’ll need to adjust.-- At minimum, the rules file must identify the date and amount fields,-and often it also specifies the date format and how many header lines-there are. Here’s a simple CSV file and a rules file for it:--Date, Description, Id, Amount-12/11/2019, Foo, 123, 10.23--# basic.csv.rules-skip 1-fields date, description, , amount-date-format %d/%m/%Y--$ hledger print -f basic.csv-2019-11-12 Foo- expenses:unknown 10.23- income:unknown -10.23-- There’s an introductory Importing CSV data tutorial on hledger.org,-and more CSV rules examples below, and a larger collection at-https://github.com/simonmichael/hledger/tree/master/examples/csv.--* Menu:--* CSV rules cheatsheet::-* separator::-* skip::-* date-format::-* timezone::-* newest-first::-* intra-day-reversed::-* decimal-mark::-* fields list::-* Field assignment::-* Field names::-* if block::-* Matchers::-* if table::-* balance-type::-* include::-* Working with CSV::-* CSV rules examples::---File: hledger.info, Node: CSV rules cheatsheet, Next: separator, Up: CSV--11.1 CSV rules cheatsheet-=========================--The following kinds of rule can appear in the rules file, in any order.-(Blank lines and lines beginning with ‘#’ or ‘;’ or ‘*’ are ignored.)--*‘separator’* declare the field separator, instead of- relying on file extension-*‘skip’* skip one or more header lines at start of file-*‘date-format’* declare how to parse CSV dates/date-times-*‘timezone’* declare the time zone of ambiguous CSV- date-times-*‘newest-first’* improve txn order when: there are multiple- records, newest first, all with the same date-*‘intra-day-reversed’* improve txn order when: same-day txns are in- opposite order to the overall file-*‘decimal-mark’* declare the decimal mark used in CSV amounts,- when ambiguous-*‘fields’ list* name CSV fields for easy reference, and- optionally assign their values to hledger- fields-*Field assignment* assign a CSV value or interpolated text value- to a hledger field-*‘if’ block* conditionally assign values to hledger fields,- or ‘skip’ a record or ‘end’ (skip rest of- file)-*‘if’ table* conditionally assign values to hledger fields,- using compact syntax-*‘balance-type’* select which type of balance- assertions/assignments to generate-*‘include’* inline another CSV rules file-- Working with CSV tips can be found below, including How CSV rules are-evaluated.---File: hledger.info, Node: separator, Next: skip, Prev: CSV rules cheatsheet, Up: CSV--11.2 ‘separator’-================--You can use the ‘separator’ rule to read other kinds of-character-separated data. The argument is any single separator-character, or the words ‘tab’ or ‘space’ (case insensitive). Eg, for-comma-separated values (CSV):--separator ,-- or for semicolon-separated values (SSV):--separator ;-- or for tab-separated values (TSV):--separator TAB-- If the input file has a ‘.csv’, ‘.ssv’ or ‘.tsv’ file extension (or a-‘csv:’, ‘ssv:’, ‘tsv:’ prefix), the appropriate separator will be-inferred automatically, and you won’t need this rule.---File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV--11.3 ‘skip’-===========--skip N-- The word ‘skip’ followed by a number (or no number, meaning 1) tells-hledger to ignore this many non-empty lines at the start of the input-data. (Empty/blank lines are skipped automatically, so you don’t need-to count those.) You’ll need this whenever your CSV data contains-header lines. Header lines skipped in this way are ignored, and not-parsed as CSV.-- ‘skip’ can also be used inside if blocks (described below), to skip-individual data records. Note records skipped in this way are still-required to be valid CSV, even though otherwise ignored.---File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV--11.4 ‘date-format’-==================--date-format DATEFMT-- This is a helper for the ‘date’ (and ‘date2’) fields. If your CSV-dates are not formatted like ‘YYYY-MM-DD’, ‘YYYY/MM/DD’ or ‘YYYY.MM.DD’,-you’ll need to add a date-format rule describing them with a-strptime-style date parsing pattern - see-https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime.-The pattern must parse the CSV date value completely. Some examples:--# MM/DD/YY-date-format %m/%d/%y--# D/M/YYYY-# The - makes leading zeros optional.-date-format %-d/%-m/%Y--# YYYY-Mmm-DD-date-format %Y-%h-%d--# M/D/YYYY HH:MM AM some other junk-# Note the time and junk must be fully parsed, though only the date is used.-date-format %-m/%-d/%Y %l:%M %p some other junk---File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV--11.5 ‘timezone’-===============--timezone TIMEZONE-- When CSV contains date-times that are implicitly in some time zone-other than yours, but containing no explicit time zone information, you-can use this rule to declare the CSV’s native time zone, which helps-prevent off-by-one dates.-- When the CSV date-times do contain time zone information, you don’t-need this rule; instead, use ‘%Z’ in ‘date-format’ (or ‘%z’, ‘%EZ’,-‘%Ez’; see the formatTime link above).-- In either of these cases, hledger will do a time-zone-aware-conversion, localising the CSV date-times to your current system time-zone. If you prefer to localise to some other time zone, eg for-reproducibility, you can (on unix at least) set the output timezone with-the TZ environment variable, eg:--$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv-- ‘timezone’ currently does not understand timezone names, except-"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".-For others, use numeric format: +HHMM or -HHMM.---File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV--11.6 ‘newest-first’-===================--hledger tries to ensure that the generated transactions will be ordered-chronologically, including intra-day transactions. Usually it can-auto-detect how the CSV records are ordered. But if it encounters CSV-where all records are on the same date, it assumes that the records are-oldest first. If in fact the CSV’s records are normally newest first,-like:--2022-10-01, txn 3...-2022-10-01, txn 2...-2022-10-01, txn 1...-- you can add the ‘newest-first’ rule to help hledger generate the-transactions in correct order.--# same-day CSV records are newest first-newest-first---File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV--11.7 ‘intra-day-reversed’-=========================--CSV records for each day are sometimes ordered in reverse compared to-the overall date order. Eg, here dates are newest first, but the-transactions on each date are oldest first:--2022-10-02, txn 3...-2022-10-02, txn 4...-2022-10-01, txn 1...-2022-10-01, txn 2...-- In this situation, add the ‘intra-day-reversed’ rule, and hledger-will compensate, improving the order of transactions.--# transactions within each day are reversed with respect to the overall date order-intra-day-reversed---File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV--11.8 ‘decimal-mark’-===================--decimal-mark .-- or:--decimal-mark ,-- hledger automatically accepts either period or comma as a decimal-mark when parsing numbers (cf Amounts). However if any numbers in the-CSV contain digit group marks, such as thousand-separating commas, you-should declare the decimal mark explicitly with this rule, to avoid-misparsed numbers.---File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV--11.9 ‘fields’ list-==================--fields FIELDNAME1, FIELDNAME2, ...-- A fields list (the word ‘fields’ followed by comma-separated field-names) is optional, but convenient. It does two things:-- 1. It names the CSV field in each column. This can be convenient if- you are referencing them in other rules, so you can say- ‘%SomeField’ instead of remembering ‘%13’.-- 2. Whenever you use one of the special hledger field names (described- below), it assigns the CSV value in this position to that hledger- field. This is the quickest way to populate hledger’s fields and- build a transaction.-- Here’s an example that says "use the 1st, 2nd and 4th fields as the-transaction’s date, description and amount; name the last two fields for-later reference; and ignore the others":--fields date, description, , amount, , , somefield, anotherfield-- In a fields list, the separator is always comma; it is unrelated to-the CSV file’s separator. Also:-- • There must be least two items in the list (at least one comma).- • Field names may not contain spaces. Spaces before/after field- names are optional.- • Field names may contain ‘_’ (underscore) or ‘-’ (hyphen).- • Fields you don’t care about can be given a dummy name or an empty- name.-- If the CSV contains column headings, it’s convenient to use these for-your field names, suitably modified (eg lower-cased with spaces replaced-by underscores).-- Sometimes you may want to alter a CSV field name to avoid assigning-to a hledger field with the same name. Eg you could call the CSV’s-"balance" field ‘balance_’ to avoid directly setting hledger’s ‘balance’-field (and generating a balance assertion).---File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV--11.10 Field assignment-======================--HLEDGERFIELD FIELDVALUE-- Field assignments are the more flexible way to assign CSV values to-hledger fields. They can be used instead of or in addition to a fields-list (see above).-- To assign a value to a hledger field, write the field name (any of-the standard hledger field/pseudo-field names, defined below), a space,-followed by a text value on the same line. This text value may-interpolate CSV fields, referenced by their 1-based position in the CSV-record (‘%N’), or by the name they were given in the fields list-(‘%CSVFIELD’).-- Some examples:--# set the amount to the 4th CSV field, with " USD" appended-amount %4 USD--# combine three fields to make a comment, containing note: and date: tags-comment note: %somefield - %anotherfield, date: %1-- Tips:-- • Interpolation strips outer whitespace (so a CSV value like ‘" 1 "’- becomes ‘1’ when interpolated) (#1051).- • Interpolations always refer to a CSV field - you can’t interpolate- a hledger field. (See Referencing other fields below).---File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV--11.11 Field names-=================--Note the two kinds of field names mentioned here, and used only in-hledger CSV rules files:-- 1. *CSV field names* (‘CSVFIELD’ in these docs): you can optionally- name the CSV columns for easy reference (since hledger doesn’t yet- automatically recognise column headings in a CSV file), by writing- arbitrary names in a ‘fields’ list, eg:-- fields When, What, Some_Id, Net, Total, Foo, Bar-- 2. Special *hledger field names* (‘HLEDGERFIELD’ in these docs): you- must set at least some of these to generate the hledger transaction- from a CSV record, by writing them as the left hand side of a field- assignment, eg:-- date %When- code %Some_Id- description %What- comment %Foo %Bar- amount1 $ %Total-- or directly in a ‘fields’ list:-- fields date, description, code, , amount1, Foo, Bar- currency $- comment %Foo %Bar-- Here are all the special hledger field names available, and what-happens when you assign values to them:--* Menu:--* date field::-* date2 field::-* status field::-* code field::-* description field::-* comment field::-* account field::-* amount field::-* currency field::-* balance field::---File: hledger.info, Node: date field, Next: date2 field, Up: Field names--11.11.1 date field---------------------Assigning to ‘date’ sets the transaction date.---File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names--11.11.2 date2 field----------------------‘date2’ sets the transaction’s secondary date, if any.---File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names--11.11.3 status field-----------------------‘status’ sets the transaction’s status, if any.---File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names--11.11.4 code field---------------------‘code’ sets the transaction’s code, if any.---File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names--11.11.5 description field----------------------------‘description’ sets the transaction’s description, if any.---File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names--11.11.6 comment field------------------------‘comment’ sets the transaction’s comment, if any.-- ‘commentN’, where N is a number, sets the Nth posting’s comment.-- You can assign multi-line comments by writing literal ‘\n’ in the-code. A comment starting with ‘\n’ will begin on a new line.-- Comments can contain tags, as usual.---File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names--11.11.7 account field------------------------Assigning to ‘accountN’, where N is 1 to 99, sets the account name of-the Nth posting, and causes that posting to be generated.-- Most often there are two postings, so you’ll want to set ‘account1’-and ‘account2’. Typically ‘account1’ is associated with the CSV file,-and is set once with a top-level assignment, while ‘account2’ is set-based on each transaction’s description, in conditional rules.-- If a posting’s account name is left unset but its amount is set (see-below), a default account name will be chosen (like "expenses:unknown"-or "income:unknown").---File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names--11.11.8 amount field-----------------------There are several "amount" field name variants, useful for different-situations:-- • ‘amountN’ sets the amount of the Nth posting, and causes that- posting to be generated. By assigning to ‘amount1’, ‘amount2’, ...- etc. you can generate up to 99 postings. Posting numbers don’t- have to be consecutive; in certain situations using a high number- might be helpful to influence the layout of postings.-- • ‘amountN-in’ and ‘amountN-out’ should be used instead, as a pair,- when and only when the amount must be obtained from two CSV fields.- Eg when the CSV has separate Debit and Credit fields instead of a- single Amount field. Note:-- • Don’t think "-in is for the first posting and -out is for the- second posting" - that’s not correct. Think: "‘amountN-in’- and ‘amountN-out’ together detect the amount for posting N, by- inspecting two CSV fields at once."- • hledger assumes both CSV fields are unsigned, and will- automatically negate the -out value.- • It also expects that at least one of the values is empty or- zero, so it knows which one to ignore. If that’s not the case- you’ll need an if rule (see Setting amounts below).-- • ‘amount’, with no posting number (and similarly, ‘amount-in’ and- ‘amount-out’ with no number) are an older syntax. We keep them for- backwards compatibility, and because they have special behaviour- that is sometimes convenient:-- • They set the amount of posting 1 and (negated) the amount of- posting 2.- • Posting 2’s amount will be converted to cost if it has a cost- price.- • Any of the newer rules for posting 1 or 2 (like ‘amount1’, or- ‘amount2-in’ and ‘amount2-out’) will take precedence. This- allows incrementally migrating old rules files to the new- syntax.-- There’s more to say about amount-setting that doesn’t fit here;-please see also "Setting amounts" below.---File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names--11.11.9 currency field-------------------------‘currency’ sets a currency symbol, to be prepended to all postings’-amounts. You can use this if the CSV amounts do not have a currency-symbol, eg if it is in a separate column.-- ‘currencyN’ prepends a currency symbol to just the Nth posting’s-amount.---File: hledger.info, Node: balance field, Prev: currency field, Up: Field names--11.11.10 balance field-------------------------‘balanceN’ sets a balance assertion amount (or if the posting amount is-left empty, a balance assignment) on posting N.-- ‘balance’ is a compatibility spelling for hledger <1.17; it is-equivalent to ‘balance1’.-- You can adjust the type of assertion/assignment with the-‘balance-type’ rule (see below).-- See Tips below for more about setting amounts and currency.---File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV--11.12 ‘if’ block-================--Rules can be applied conditionally, depending on patterns in the CSV-data. This allows flexibility; in particular, it is how you can-categorise transactions, selecting an appropriate account name based on-their description (for example). There are two ways to write-conditional rules: "if blocks", described here, and "if tables",-described below.-- An if block is the word ‘if’ and one or more "matcher" expressions-(can be a word or phrase), one per line, starting either on the same or-next line; followed by one or more indented rules. Eg,--if MATCHER- RULE-- or--if-MATCHER-MATCHER-MATCHER- RULE- RULE-- If any of the matchers succeeds, all of the indented rules will be-applied. They are usually field assignments, but the following special-rules may also be used within an if block:-- • ‘skip’ - skips the matched CSV record (generating no transaction- from it)- • ‘end’ - skips the rest of the current CSV file.-- Some examples:--# if the record contains "groceries", set account2 to "expenses:groceries"-if groceries- account2 expenses:groceries--# if the record contains any of these phrases, set account2 and a transaction comment as shown-if-monthly service fee-atm transaction fee-banking thru software- account2 expenses:business:banking- comment XXX deductible ? check it--# if an empty record is seen (assuming five fields), ignore the rest of the CSV file-if ,,,,- end---File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV--11.13 Matchers-==============--There are two kinds:-- 1. A record matcher is a word or single-line text fragment or regular- expression (‘REGEX’), which hledger will try to match- case-insensitively anywhere within the CSV record.- Eg: ‘whole foods’-- 2. A field matcher is preceded with a percent sign and CSV field name- (‘%CSVFIELD REGEX’). hledger will try to match these just within- the named CSV field.- Eg: ‘%date 2023’-- The regular expression is (as usual in hledger) a POSIX extended-regular expression, that also supports GNU word boundaries (‘\b’, ‘\B’,-‘\<’, ‘\>’), and nothing else. If you have trouble, see "Regular-expressions" in the hledger manual-(https://hledger.org/hledger.html#regular-expressions).-- With record matchers, it’s important to know that the record matched-is not the original CSV record, but a modified one: separators will be-converted to commas, and enclosing double quotes (but not enclosing-whitespace) are removed. So for example, when reading an SSV file, if-the original record was:--2020-01-01; "Acme, Inc."; 1,000-- the regex would see, and try to match, this modified record text:--2020-01-01,Acme, Inc., 1,000-- When an if block has multiple matchers, they are combined as follows:-- • By default they are OR’d (any one of them can match)- • When a matcher is preceded by ampersand (‘&’) it will be AND’ed- with the previous matcher (both of them must match).-- There’s not yet an easy syntax to negate a matcher.---File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV--11.14 ‘if’ table-================--"if tables" are an alternative to if blocks; they can express many-matchers and field assignments in a more compact tabular format, like-this:--if,HLEDGERFIELD1,HLEDGERFIELD2,...-MATCHERA,VALUE1,VALUE2,...-MATCHERB,VALUE1,VALUE2,...-MATCHERC,VALUE1,VALUE2,...-<empty line>-- The first character after ‘if’ is taken to be the separator for the-rest of the table. It should be a non-alphanumeric character like ‘,’-or ‘|’ that does not appear anywhere else in the table. (Note: it is-unrelated to the CSV file’s separator.) Whitespace can be used in the-matcher lines for readability, but not in the if line currently. The-table must be terminated by an empty line (or end of file). Each line-must contain the same number of separators; empty values are allowed.-- The above means: try all of the matchers; whenever a matcher-succeeds, assign all of the values on that line to the corresponding-hledger fields; later lines can overrider earlier ones. It is-equivalent to this sequence of if blocks:--if MATCHERA- HLEDGERFIELD1 VALUE1- HLEDGERFIELD2 VALUE2- ...--if MATCHERB- HLEDGERFIELD1 VALUE1- HLEDGERFIELD2 VALUE2- ...--if MATCHERC- HLEDGERFIELD1 VALUE1- HLEDGERFIELD2 VALUE2- ...-- Example:--if,account2,comment-atm transaction fee,expenses:business:banking,deductible? check it-%description groceries,expenses:groceries,-2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out---File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV--11.15 ‘balance-type’-====================--Balance assertions generated by assigning to balanceN are of the simple-‘=’ type by default, which is a single-commodity, subaccount-excluding-assertion. You may find the subaccount-including variants more useful,-eg if you have created some virtual subaccounts of checking to help with-budgeting. You can select a different type of assertion with the-‘balance-type’ rule:--# balance assertions will consider all commodities and all subaccounts-balance-type ==*-- Here are the balance assertion types for quick reference:--= single commodity, exclude subaccounts-=* single commodity, include subaccounts-== multi commodity, exclude subaccounts-==* multi commodity, include subaccounts---File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV--11.16 ‘include’-===============--include RULESFILE-- This includes the contents of another CSV rules file at this point.-‘RULESFILE’ is an absolute file path or a path relative to the current-file’s directory. This can be useful for sharing common rules between-several rules files, eg:--# someaccount.csv.rules--## someaccount-specific rules-fields date,description,amount-account1 assets:someaccount-account2 expenses:misc--## common rules-include categorisation.rules---File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV--11.17 Working with CSV-======================--Some tips:--* Menu:--* Rapid feedback::-* Valid CSV::-* File Extension::-* Reading CSV from standard input::-* Reading multiple CSV files::-* Valid transactions::-* Deduplicating importing::-* Setting amounts::-* Amount signs::-* Setting currency/commodity::-* Amount decimal places::-* Referencing other fields::-* How CSV rules are evaluated::-* Well factored rules::---File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV--11.17.1 Rapid feedback-------------------------It’s a good idea to get rapid feedback while creating/troubleshooting-CSV rules. Here’s a good way, using entr from eradman.com/entrproject:--$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'-- A desc: query (eg) is used to select just one, or a few, transactions-of interest. "bash -c" is used to run multiple commands, so we can echo-a separator each time the command re-runs, making it easier to read the-output.---File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV--11.17.2 Valid CSV--------------------Note that hledger will only accept valid CSV conforming to RFC 4180, and-equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab-as separators). This means, eg:-- • Values may be enclosed in double quotes, or not. Enclosing in- single quotes is not allowed. (Eg ‘'A','B'’ is rejected.)- • When values are enclosed in double quotes, spaces outside the- quotes are not allowed. (Eg ‘"A", "B"’ is rejected.)- • When values are not enclosed in quotes, they may not contain double- quotes. (Eg ‘A"A, B’ is rejected.)-- If your CSV/SSV/TSV is not valid in this sense, you’ll need to-transform it before reading with hledger. Try using sed, or a more-permissive CSV parser like python’s csv lib.---File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV--11.17.3 File Extension-------------------------To help hledger choose the CSV file reader and show the right error-messages (and choose the right field separator character by default),-it’s best if CSV/SSV/TSV files are named with a ‘.csv’, ‘.ssv’ or ‘.tsv’-filename extension. (More about this at Data formats.)-- When reading files with the "wrong" extension, you can ensure the CSV-reader (and the default field separator) by prefixing the file path with-‘csv:’, ‘ssv:’ or ‘tsv:’: Eg:--$ hledger -f ssv:foo.dat print-- You can also override the default field separator with a separator-rule if needed.---File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV--11.17.4 Reading CSV from standard input------------------------------------------You’ll need the file format prefix when reading CSV from stdin also,-since hledger assumes journal format by default. Eg:--$ cat foo.dat | hledger -f ssv:- print---File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Reading CSV from standard input, Up: Working with CSV--11.17.5 Reading multiple CSV files-------------------------------------If you use multiple ‘-f’ options to read multiple CSV files at once,-hledger will look for a correspondingly-named rules file for each CSV-file. But if you use the ‘--rules-file’ option, that rules file will be-used for all the CSV files.---File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Working with CSV--11.17.6 Valid transactions-----------------------------After reading a CSV file, hledger post-processes and validates the-generated journal entries as it would for a journal file - balancing-them, applying balance assignments, and canonicalising amount styles.-Any errors at this stage will be reported in the usual way, displaying-the problem entry.-- There is one exception: balance assertions, if you have generated-them, will not be checked, since normally these will work only when the-CSV data is part of the main journal. If you do need to check balance-assertions generated from CSV right away, pipe into another hledger:--$ hledger -f file.csv print | hledger -f- print---File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV--11.17.7 Deduplicating, importing-----------------------------------When you download a CSV file periodically, eg to get your latest bank-transactions, the new file may overlap with the old one, containing some-of the same records.-- The import command will (a) detect the new transactions, and (b)-append just those transactions to your main journal. It is idempotent,-so you don’t have to remember how many times you ran it or with which-version of the CSV. (It keeps state in a hidden ‘.latest.FILE.csv’-file.) This is the easiest way to import CSV data. Eg:--# download the latest CSV files, then run this command.-# Note, no -f flags needed here.-$ hledger import *.csv [--dry]-- This method works for most CSV files. (Where records have a stable-chronological order, and new records appear only at the new end.)-- A number of other tools and workflows, hledger-specific and-otherwise, exist for converting, deduplicating, classifying and managing-CSV data. See:-- • https://hledger.org/cookbook.html#setups-and-workflows- • https://plaintextaccounting.org -> data import/conversion---File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV--11.17.8 Setting amounts--------------------------Continuing from amount field above, here are more tips on handling-various amount-setting situations:-- 1. *If the amount is in a single CSV field:*-- a. *If its sign indicates direction of flow:*- Assign it to ‘amountN’, to set the Nth posting’s amount. N is- usually 1 or 2 but can go up to 99.-- b. *If another field indicates direction of flow:*- Use one or more conditional rules to set the appropriate- amount sign. Eg:-- # assume a withdrawal unless Type contains "deposit":- amount1 -%Amount- if %Type deposit- amount1 %Amount-- 2. *If the amount is in one of two CSV fields (eg Debit and Credit):*-- a. *If both fields are unsigned:*- Assign the fields to ‘amountN-in’ and ‘amountN-out’. This- sets posting N’s amount to whichever of these has a non-zero- value. If it’s the -out value, the amount will be negated.-- b. *If either field is signed:*- Use a conditional rule to flip the sign when needed. Eg- below, the -out value already has a minus sign so we undo- hledger’s automatic negating by negating once more (but only- if the field is non-empty, so that we don’t leave a minus sign- by itself):-- fields date, description, amount1-in, amount1-out- if %amount1-out [1-9]- amount1-out -%amount1-out-- c. *If both fields can contain a non-zero value (or both can be- empty):*- The -in/-out rules normally choose the value which is- non-zero/non-empty. Some value pairs can be ambiguous, such- as ‘1’ and ‘none’. For such cases, use conditional rules to- help select the amount. Eg, to handle the above you could- select the value containing non-zero digits:-- fields date, description, in, out- if %in [1-9]- amount1 %in- if %out [1-9]- amount1 %out-- 3. *If you want posting 2’s amount converted to cost:*- Use the unnumbered ‘amount’ (or ‘amount-in’ and ‘amount-out’)- syntax.-- 4. *If the CSV has only balance amounts, not transaction amounts:*- Assign to ‘balanceN’, to set a balance assignment on the Nth- posting, causing the posting’s amount to be calculated- automatically. ‘balance’ with no number is equivalent to- ‘balance1’. In this situation hledger is more likely to guess the- wrong default account name, so you may need to set that explicitly.---File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV--11.17.9 Amount signs-----------------------There is some special handling for amount signs, to simplify parsing and-sign-flipping:-- • *If an amount value begins with a plus sign:*- that will be removed: ‘+AMT’ becomes ‘AMT’-- • *If an amount value is parenthesised:*- it will be de-parenthesised and sign-flipped: ‘(AMT)’ becomes- ‘-AMT’-- • *If an amount value has two minus signs (or two sets of- parentheses, or a minus sign and parentheses):*- they cancel out and will be removed: ‘--AMT’ or ‘-(AMT)’ becomes- ‘AMT’-- • *If an amount value contains just a sign (or just a set of- parentheses):*- that is removed, making it an empty value. ‘"+"’ or ‘"-"’ or- ‘"()"’ becomes ‘""’.---File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV--11.17.10 Setting currency/commodity--------------------------------------If the currency/commodity symbol is included in the CSV’s amount-field(s):--2020-01-01,foo,$123.00-- you don’t have to do anything special for the commodity symbol, it-will be assigned as part of the amount. Eg:--fields date,description,amount--2020-01-01 foo- expenses:unknown $123.00- income:unknown $-123.00-- If the currency is provided as a separate CSV field:--2020-01-01,foo,USD,123.00-- You can assign that to the ‘currency’ pseudo-field, which has the-special effect of prepending itself to every amount in the transaction-(on the left, with no separating space):--fields date,description,currency,amount--2020-01-01 foo- expenses:unknown USD123.00- income:unknown USD-123.00-- Or, you can use a field assignment to construct the amount yourself,-with more control. Eg to put the symbol on the right, and separated by-a space:--fields date,description,cur,amt-amount %amt %cur--2020-01-01 foo- expenses:unknown 123.00 USD- income:unknown -123.00 USD-- Note we used a temporary field name (‘cur’) that is not ‘currency’ --that would trigger the prepending effect, which we don’t want here.---File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV--11.17.11 Amount decimal places---------------------------------Like amounts in a journal file, the amounts generated by CSV rules like-‘amount1’ influence commodity display styles, such as the number of-decimal places displayed in reports.-- The original amounts as written in the CSV file do not affect display-style (because we don’t yet reliably know their commodity).---File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV--11.17.12 Referencing other fields------------------------------------In field assignments, you can interpolate only CSV fields, not hledger-fields. In the example below, there’s both a CSV field and a hledger-field named amount1, but %amount1 always means the CSV field, not the-hledger field:--# Name the third CSV field "amount1"-fields date,description,amount1--# Set hledger's amount1 to the CSV amount1 field followed by USD-amount1 %amount1 USD--# Set comment to the CSV amount1 (not the amount1 assigned above)-comment %amount1-- Here, since there’s no CSV amount1 field, %amount1 will produce a-literal "amount1":--fields date,description,csvamount-amount1 %csvamount USD-# Can't interpolate amount1 here-comment %amount1-- When there are multiple field assignments to the same hledger field,-only the last one takes effect. Here, comment’s value will be be B, or-C if "something" is matched, but never A:--comment A-comment B-if something- comment C---File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV--11.17.13 How CSV rules are evaluated---------------------------------------Here’s how to think of CSV rules being evaluated (if you really need-to). First,-- • ‘include’ - all includes are inlined, from top to bottom, depth- first. (At each include point the file is inlined and scanned for- further includes, recursively, before proceeding.)-- Then "global" rules are evaluated, top to bottom. If a rule is-repeated, the last one wins:-- • ‘skip’ (at top level)- • ‘date-format’- • ‘newest-first’- • ‘fields’ - names the CSV fields, optionally sets up initial- assignments to hledger fields-- Then for each CSV record in turn:-- • test all ‘if’ blocks. If any of them contain a ‘end’ rule, skip- all remaining CSV records. Otherwise if any of them contain a- ‘skip’ rule, skip that many CSV records. If there are multiple- matched ‘skip’ rules, the first one wins.- • collect all field assignments at top level and in matched ‘if’- blocks. When there are multiple assignments for a field, keep only- the last one.- • compute a value for each hledger field - either the one that was- assigned to it (and interpolate the %CSVFIELD references), or a- default- • generate a hledger transaction (journal entry) from these values.-- This is all part of the CSV reader, one of several readers hledger-can use to parse input files. When all files have been read-successfully, the transactions are passed as input to whichever hledger-command the user specified.---File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV--11.17.14 Well factored rules-------------------------------Some things than can help reduce duplication and complexity in rules-files:-- • Extracting common rules usable with multiple CSV files into a- ‘common.rules’, and adding ‘include common.rules’ to each CSV’s- rules file.-- • Splitting if blocks into smaller if blocks, extracting the- frequently used parts.---File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV--11.18 CSV rules examples-========================--* Menu:--* Bank of Ireland::-* Coinbase::-* Amazon::-* Paypal::---File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples--11.18.1 Bank of Ireland--------------------------Here’s a CSV with two amount fields (Debit and Credit), and a balance-field, which we can use to add balance assertions, which is not-necessary but provides extra error checking:--Date,Details,Debit,Credit,Balance-07/12/2012,LODGMENT 529898,,10.0,131.21-07/12/2012,PAYMENT,5,,126--# bankofireland-checking.csv.rules--# skip the header line-skip--# name the csv fields, and assign some of them as journal entry fields-fields date, description, amount-out, amount-in, balance--# We generate balance assertions by assigning to "balance"-# above, but you may sometimes need to remove these because:-#-# - the CSV balance differs from the true balance,-# by up to 0.0000000000005 in my experience-#-# - it is sometimes calculated based on non-chronological ordering,-# eg when multiple transactions clear on the same day--# date is in UK/Ireland format-date-format %d/%m/%Y--# set the currency-currency EUR--# set the base account for all txns-account1 assets:bank:boi:checking--$ hledger -f bankofireland-checking.csv print-2012-12-07 LODGMENT 529898- assets:bank:boi:checking EUR10.0 = EUR131.2- income:unknown EUR-10.0--2012-12-07 PAYMENT- assets:bank:boi:checking EUR-5.0 = EUR126.0- expenses:unknown EUR5.0-- The balance assertions don’t raise an error above, because we’re-reading directly from CSV, but they will be checked if these entries are-imported into a journal file.---File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples--11.18.2 Coinbase-------------------A simple example with some CSV from Coinbase. The spot price is-recorded using cost notation. The legacy ‘amount’ field name-conveniently sets amount 2 (posting 2’s amount) to the total cost.--# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes-# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"--# coinbase.csv.rules-skip 1-fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes-date %Timestamp-date-format %Y-%m-%dT%T%Z-description %Notes-account1 assets:coinbase:cc-amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency--$ hledger print -f coinbase.csv-2021-12-30 Received 100.00 USDC from an external account- assets:coinbase:cc 100 USDC @ 0.740000 GBP- income:unknown -74.000000 GBP---File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples--11.18.3 Amazon-----------------Here we convert amazon.com order history, and use an if block to-generate a third posting if there’s a fee. (In practice you’d probably-get this data from your bank instead, but it’s an example.)--"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"-"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"-"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"--# amazon-orders.csv.rules--# skip one header line-skip 1--# name the csv fields, and assign the transaction's date, amount and code.-# Avoided the "status" and "amount" hledger field names to prevent confusion.-fields date, _, toorfrom, name, amzstatus, amzamount, fees, code--# how to parse the date-date-format %b %-d, %Y--# combine two fields to make the description-description %toorfrom %name--# save the status as a tag-comment status:%amzstatus--# set the base account for all transactions-account1 assets:amazon-# leave amount1 blank so it can balance the other(s).-# I'm assuming amzamount excludes the fees, don't remember--# set a generic account2-account2 expenses:misc-amount2 %amzamount-# and maybe refine it further:-#include categorisation.rules--# add a third posting for fees, but only if they are non-zero.-if %fees [1-9]- account3 expenses:fees- amount3 %fees--$ hledger -f amazon-orders.csv print-2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed- assets:amazon- expenses:misc $20.00--2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed- assets:amazon- expenses:misc $25.00- expenses:fees $1.00---File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples--11.18.4 Paypal-----------------Here’s a real-world rules file for (customised) Paypal CSV, with some-Paypal-specific rules, and a second rules file included:--"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"-"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""-"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""-"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""-"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""-"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""-"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""-"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""--# paypal-custom.csv.rules--# Tips:-# Export from Activity -> Statements -> Custom -> Activity download-# Suggested transaction type: "Balance affecting"-# Paypal's default fields in 2018 were:-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"-# This rules file assumes the following more detailed fields, configured in "Customize report fields":-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"--fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note--skip 1--date-format %-m/%-d/%Y--# ignore some paypal events-if-In Progress-Temporary Hold-Update to- skip--# add more fields to the description-description %description_ %itemtitle--# save some other fields as tags-comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_--# convert to short currency symbols-if %currency USD- currency $-if %currency EUR- currency E-if %currency GBP- currency P--# generate postings--# the first posting will be the money leaving/entering my paypal account-# (negative means leaving my account, in all amount fields)-account1 assets:online:paypal-amount1 %netamount--# the second posting will be money sent to/received from other party-# (account2 is set below)-amount2 -%grossamount--# if there's a fee, add a third posting for the money taken by paypal.-if %feeamount [1-9]- account3 expenses:banking:paypal- amount3 -%feeamount- comment3 business:--# choose an account for the second posting--# override the default account names:-# if the amount is positive, it's income (a debit)-if %grossamount ^[^-]- account2 income:unknown-# if negative, it's an expense (a credit)-if %grossamount ^-- account2 expenses:unknown--# apply common rules for setting account2 & other tweaks-include common.rules--# apply some overrides specific to this csv--# Transfers from/to bank. These are usually marked Pending,-# which can be disregarded in this case.-if-Bank Account-Bank Deposit to PP Account- description %type for %referencetxnid %itemtitle- account2 assets:bank:wf:pchecking- account1 assets:online:paypal--# Currency conversions-if Currency Conversion- account2 equity:currency conversion--# common.rules--if-darcs-noble benefactor- account2 revenues:foss donations:darcshub- comment2 business:--if-Calm Radio- account2 expenses:online:apps--if-electronic frontier foundation-Patreon-wikimedia-Advent of Code- account2 expenses:dues--if Google- account2 expenses:online:apps- description google | music--$ hledger -f paypal-custom.csv print-2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed- assets:online:paypal $-6.99 = $-6.99- expenses:online:apps $6.99--2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending- assets:online:paypal $6.99 = $0.00- assets:bank:wf:pchecking $-6.99--2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed- assets:online:paypal $-7.00 = $-7.00- expenses:dues $7.00--2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending- assets:online:paypal $7.00 = $0.00- assets:bank:wf:pchecking $-7.00--2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed- assets:online:paypal $-2.00 = $-2.00- expenses:dues $2.00- expenses:banking:paypal ; business:--2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending- assets:online:paypal $2.00 = $0.00- assets:bank:wf:pchecking $-2.00--2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed- assets:online:paypal $9.41 = $9.41- revenues:foss donations:darcshub $-10.00 ; business:- expenses:banking:paypal $0.59 ; business:---File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top--12 Timeclock-************--The time logging format of timeclock.el, as read by hledger.-- hledger can read time logs in timeclock format. As with Ledger,-these are (a subset of) timeclock.el’s format, containing clock-in and-clock-out entries as in the example below. The date is a simple date.-The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are-optional. The timezone, if present, must be four digits and is ignored-(currently the time is always interpreted as a local time). Lines-beginning with ‘#’ or ‘;’ or ‘*’, and blank lines, are ignored.--i 2015/03/30 09:00:00 some:account name optional description after two spaces-o 2015/03/30 09:20:00-i 2015/03/31 22:21:45 another account-o 2015/04/01 02:00:34-- hledger treats each clock-in/clock-out pair as a transaction posting-some number of hours to an account. Or if the session spans more than-one day, it is split into several transactions, one for each day. For-the above time log, ‘hledger print’ generates these journal entries:--$ hledger -f t.timeclock print-2015-03-30 * optional description after two spaces- (some:account name) 0.33h--2015-03-31 * 22:21-23:59- (another account) 1.64h--2015-04-01 * 00:00-02:00- (another account) 2.01h-- Here is a sample.timeclock to download and some queries to try:--$ hledger -f sample.timeclock balance # current time balances-$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009-$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week-- To generate time logs, ie to clock in and clock out, you could:-- • use emacs and the built-in timeclock.el, or the extended- timeclock-x.el and perhaps the extras in ledgerutils.el-- • at the command line, use these bash aliases: ‘shell alias ti="echo- i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o- `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"’-- • or use the old ‘ti’ and ‘to’ scripts in the ledger 2.x repository.- These rely on a "timeclock" executable which I think is just the- ledger 2 executable renamed.---File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top--13 Timedot-**********--‘timedot’ format is hledger’s human-friendly time logging format.-Compared to ‘timeclock’ format, it is-- • convenient for quick, approximate, and retroactive time logging- • readable: you can see at a glance where time was spent.-- A timedot file contains a series of day entries, which might look-like this:--2021-08-04-hom:errands .... ....-fos:hledger:timedot .. ; docs-per:admin:finance -- hledger reads this as three time transactions on this day, with each-dot representing a quarter-hour spent:--$ hledger -f a.timedot print # .timedot file extension activates the timedot reader-2021-08-04 *- (hom:errands) 2.00--2021-08-04 *- (fos:hledger:timedot) 0.50--2021-08-04 *- (per:admin:finance) 0-- A day entry begins with a date line:-- • a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D).-- Optionally this can be followed on the same line by-- • a common *transaction description* for this day- • a common *transaction comment* for this day, after a semicolon- (‘;’).-- After the date line are zero or more optionally-indented time-transaction lines, consisting of:-- • an *account name* - any word or phrase, usually a hledger-style- account name.- • *two or more spaces* - a field separator, required if there is an- amount (as in journal format).- • a *timedot amount* - dots representing quarter hours, or a number- representing hours.- • an optional *comment* beginning with semicolon. This is ignored.-- In more detail, timedot amounts can be:-- • *dots*: zero or more period characters, each representing one- quarter-hour. Spaces are ignored and can be used for grouping.- Eg: ‘.... ..’-- • a *number*, representing hours. Eg: ‘1.5’-- • a *number immediately followed by a unit symbol* ‘s’, ‘m’, ‘h’,- ‘d’, ‘w’, ‘mo’, or ‘y’, representing seconds, minutes, hours, days- weeks, months or years. Eg ‘1.5h’ or ‘90m’. The following- equivalencies are assumed:- ‘60s’ = ‘1m’, ‘60m’ = ‘1h’, ‘24h’ = ‘1d’, ‘7d’ = ‘1w’, ‘30d’ =- ‘1mo’, ‘365d’ = ‘1y’. (This unit will not be visible in the- generated transaction amount, which is always in hours.)-- There is some added flexibility to help with keeping time log data in-the same file as your notes, todo lists, etc.:-- • Blank lines and lines beginning with ‘#’ or ‘;’ are ignored.-- • Before the first date line, lines beginning with ‘*’ are ignored.- From the first date line onward, a sequence of ‘*’’s followed by a- space at beginning of lines (ie, the headline prefix used by Emacs- Org mode) is ignored. This means the time log can be kept under an- Org headline, and date lines or time transaction lines can be Org- headlines.-- • Lines not ending with a double-space and amount are parsed as- transactions with zero amount. (Most hledger reports hide these by- default; add -E to see them.)-- More examples:--# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.-2016/2/1-inc:client1 .... .... .... .... .... ....-fos:haskell .... ..-biz:research .--2016/2/2-inc:client1 .... ....-biz:research .--2016/2/3-inc:client1 4-fos:hledger 3-biz:research 1--* Time log-** 2020-01-01-*** adm:time .-*** adm:finance .--* 2020 Work Diary-** Q1-*** 2020-02-29-**** DONE-0700 yoga-**** UNPLANNED-**** BEGUN-hom:chores- cleaning ...- water plants- outdoor - one full watering can- indoor - light watering-**** TODO-adm:planning: trip-*** LATER-- Reporting:--$ hledger -f a.timedot print date:2016/2/2-2016-02-02 *- (inc:client1) 2.00--2016-02-02 *- (biz:research) 0.25--$ hledger -f a.timedot bal --daily --tree-Balance changes in 2016-02-01-2016-02-03:-- || 2016-02-01d 2016-02-02d 2016-02-03d -============++========================================- biz || 0.25 0.25 1.00 - research || 0.25 0.25 1.00 - fos || 1.50 0 3.00 - haskell || 1.50 0 0 - hledger || 0 0 3.00 - inc || 6.00 2.00 4.00 - client1 || 6.00 2.00 4.00 -------------++----------------------------------------- || 7.75 2.25 8.00 -- Using period instead of colon as account name separator:--2016/2/4-fos.hledger.timedot 4-fos.ledger ..--$ hledger -f a.timedot --alias /\\./=: bal --tree- 4.50 fos- 4.00 hledger:timedot- 0.50 ledger---------------------- 4.50-- A sample.timedot file.---File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top--14 PART 3: REPORTING CONCEPTS-*****************************---File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top--15 Time periods-***************--* Menu:--* Report start & end date::-* Smart dates::-* Report intervals::-* Date adjustment::-* Period expressions::---File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods--15.1 Report start & end date-============================--By default, most hledger reports will show the full span of time-represented by the journal. The report start date will be the earliest-transaction or posting date, and the report end date will be the latest-transaction, posting, or market price date.-- Often you will want to see a shorter time span, such as the current-month. You can specify a start and/or end date using ‘-b/--begin’,-‘-e/--end’, ‘-p/--period’ or a ‘date:’ query (described below). All of-these accept the smart date syntax (below).-- Some notes:-- • End dates are exclusive, as in Ledger, so you should write the date- _after_ the last day you want to see in the report.- • As noted in reporting options: among start/end dates specified with- _options_, the last (i.e. right-most) option takes precedence.- • The effective report start and end dates are the intersection of- the start/end dates from options and that from ‘date:’ queries.- That is, ‘date:2019-01 date:2019 -p'2000 to 2030'’ yields January- 2019, the smallest common time span.- • In some cases a report interval will adjust start/end dates to fall- on interval boundaries (see below).-- Examples:--‘-b begin on St. Patrick’s day 2016-2016/3/17’-‘-e 12/1’ end at the start of december 1st of the current year- (11/30 will be the last date included)-‘-b all transactions on or after the 1st of the current month-thismonth’-‘-p all transactions in the current month-thismonth’-‘date:2016/3/17..’the above written as queries instead (‘..’ can also be- replaced with ‘-’)-‘date:..12/1’-‘date:thismonth..’-‘date:thismonth’---File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods--15.2 Smart dates-================--hledger’s user interfaces accept a "smart date" syntax for added-convenience. Smart dates optionally can be relative to today’s date, be-written with english words, and have less-significant parts omitted-(missing parts are inferred as 1). Some examples:--‘2004/10/1’, exact date, several separators allowed. Year-‘2004-01-01’, is 4+ digits, month is 1-12, day is 1-31-‘2004.9.1’-‘2004’ start of year-‘2004/10’ start of month-‘10/1’ month and day in current year-‘21’ day in current month-‘october, oct’ start of month in current year-‘yesterday, today, -1, 0, 1 days from today-tomorrow’-‘last/this/next -1, 0, 1 periods from the current period-day/week/month/quarter/year’-‘in n n periods from the current period-days/weeks/months/quarters/years’-‘n n periods from the current period-days/weeks/months/quarters/years-ahead’-‘n -n periods from the current period-days/weeks/months/quarters/years-ago’-‘20181201’ 8 digit YYYYMMDD with valid year month and- day-‘201812’ 6 digit YYYYMM with valid year and month-- Some counterexamples - malformed digit sequences might give-surprising results:--‘201813’ 6 digits with an invalid month is parsed as start of- 6-digit year-‘20181301’ 8 digits with an invalid month is parsed as start of- 8-digit year-‘20181232’ 8 digits with an invalid day gives an error-‘201801012’ 9+ digits beginning with a valid YYYYMMDD gives an error-- "Today’s date" can be overridden with the ‘--today’ option, in case-it’s needed for testing or for recreating old reports. (Except for-periodic transaction rules, which are not affected by ‘--today’.)---File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods--15.3 Report intervals-=====================--A report interval can be specified so that reports like register,-balance or activity become multi-period, showing each subperiod as a-separate row or column.-- The following standard intervals can be enabled with command-line-flags:-- • ‘-D/--daily’- • ‘-W/--weekly’- • ‘-M/--monthly’- • ‘-Q/--quarterly’- • ‘-Y/--yearly’-- More complex intervals can be specified using ‘-p/--period’,-described below.---File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods--15.4 Date adjustment-====================--With a report interval (other than daily), report start / end dates-which have not been specified explicitly and in full (eg not ‘-b-2023-01-01’, but ‘-b 2023-01’ or ‘-b 2023’ or unspecified) are-considered flexible:-- • A flexible start date will be automatically adjusted earlier if- needed to fall on a natural interval boundary.- • Similarly, a flexible end date will be adjusted later if needed to- make the last period a whole interval (the same length as the- others).-- This is convenient for producing clean periodic reports (this is-traditional hledger behaviour). By contrast, fully-specified exact-dates will not be adjusted (this is new in hledger 1.29).-- An example: with a journal whose first date is 2023-01-10 and last-date is 2023-03-20:-- • ‘hledger bal -M -b 2023/1/15 -e 2023/3/10’- The report periods will begin on the 15th day of each month,- starting from 2023-01-15, and the last period’s last day will be- 2023-03-09. (Exact start and end dates, neither is adjusted.)-- • ‘hledger bal -M -b 2023-01 -e 2023-04’ or ‘hledger bal -M’- The report periods will begin on the 1st of each month, starting- from 2023-01-01, and the last period’s last day will be 2023-03-31.- (Flexible start and end dates, both are adjusted.)---File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods--15.5 Period expressions-=======================--The ‘-p/--period’ option specifies a period expression, which is a-compact way of expressing a start date, end date, and/or report-interval.-- Here’s a period expression with a start and end date (specifying the-first quarter of 2009):--‘-p "from 2009/1/1 to 2009/4/1"’-- Several keywords like "from" and "to" are supported for readability;-these are optional. "to" can also be written as ".." or "-". The-spaces are also optional, as long as you don’t run two dates together.-So the following are equivalent to the above:--‘-p "2009/1/1 2009/4/1"’-‘-p2009/1/1to2009/4/1’-‘-p2009/1/1..2009/4/1’-- Dates are smart dates, so if the current year is 2009, these are also-equivalent to the above:--‘-p "1/1 4/1"’-‘-p "jan-apr"’-‘-p "this year to 4/1"’-- If you specify only one date, the missing start or end date will be-the earliest or latest transaction date in the journal:--‘-p "from 2009/1/1"’ everything after january 1, 2009-‘-p "since 2009/1"’ the same, since is a synonym-‘-p "from 2009"’ the same-‘-p "to 2009"’ everything before january 1, 2009-- You can also specify a period by writing a single partial or full-date:--‘-p "2009"’ the year 2009; equivalent to “2009/1/1 to 2010/1/1”-‘-p "2009/1"’ the month of january 2009; equivalent to “2009/1/1 to- 2009/2/1”-‘-p the first day of 2009; equivalent to “2009/1/1 to-"2009/1/1"’ 2009/1/2”-- or by using the "Q" quarter-year syntax (case insensitive):--‘-p "2009Q1"’ first quarter of 2009, equivalent to “2009/1/1 to- 2009/4/1”-‘-p "q4"’ fourth quarter of the current year--* Menu:--* Period expressions with a report interval::-* More complex report intervals::-* Multiple weekday intervals::---File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions--15.5.1 Period expressions with a report interval---------------------------------------------------A period expression can also begin with a report interval, separated-from the start/end dates (if any) by a space or the word ‘in’:--‘-p "weekly from 2009/1/1 to 2009/4/1"’-‘-p "monthly in 2008"’-‘-p "quarterly"’---File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions--15.5.2 More complex report intervals---------------------------------------Some more complex intervals can be specified within period expressions,-such as:-- • ‘biweekly’ (every two weeks)- • ‘fortnightly’- • ‘bimonthly’ (every two months)- • ‘every day|week|month|quarter|year’- • ‘every N days|weeks|months|quarters|years’-- Weekly on a custom day:-- • ‘every Nth day of week’ (‘th’, ‘nd’, ‘rd’, or ‘st’ are all accepted- after the number)- • ‘every WEEKDAYNAME’ (full or three-letter english weekday name,- case insensitive)-- Monthly on a custom day:-- • ‘every Nth day [of month]’- • ‘every Nth WEEKDAYNAME [of month]’-- Yearly on a custom day:-- • ‘every MM/DD [of year]’ (month number and day of month number)- • ‘every MONTHNAME DDth [of year]’ (full or three-letter english- month name, case insensitive, and day of month number)- • ‘every DDth MONTHNAME [of year]’ (equivalent to the above)-- Examples:--‘-p "bimonthly from-2008"’-‘-p "every 2 weeks"’-‘-p "every 5 months from-2009/03"’-‘-p "every 2nd day of periods will go from Tue to Tue-week"’-‘-p "every Tue"’ same-‘-p "every 15th day"’ period boundaries will be on 15th of each- month-‘-p "every 2nd Monday"’ period boundaries will be on second Monday- of each month-‘-p "every 11/05"’ yearly periods with boundaries on 5th of- November-‘-p "every 5th November"’ same-‘-p "every Nov 5th"’ same-- Show historical balances at end of the 15th day of each month (N is-an end date, exclusive as always):--$ hledger balance -H -p "every 16th day"-- Group postings from the start of wednesday to end of the following-tuesday (N is both (inclusive) start date and (exclusive) end date):--$ hledger register checking -p "every 3rd day of week"---File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions--15.5.3 Multiple weekday intervals------------------------------------This special form is also supported:-- • ‘every WEEKDAYNAME,WEEKDAYNAME,...’ (full or three-letter english- weekday names, case insensitive)-- Also, ‘weekday’ and ‘weekendday’ are shorthand for-‘mon,tue,wed,thu,fri’ and ‘sat,sun’.-- This is mainly intended for use with ‘--forecast’, to generate-periodic transactions on arbitrary days of the week. It may be less-useful with ‘-p’, since it divides each week into subperiods of unequal-length, which is unusual. (Related: #1632)-- Examples:--‘-p "every dates will be Mon, Wed, Fri; periods will be-mon,wed,fri"’ Mon-Tue, Wed-Thu, Fri-Sun-‘-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will-weekday"’ be Mon, Tue, Wed, Thu, Fri-Sun-‘-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri-weekendday"’---File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top--16 Depth-********--With the ‘--depth NUM’ option (short form: ‘-NUM’), reports will show-accounts only to the specified depth, hiding deeper subaccounts. Use-this when you want a summary with less detail. This flag has the same-effect as a ‘depth:’ query argument: ‘depth:2’, ‘--depth=2’ or ‘-2’ are-equivalent.---File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top--17 Queries-**********--One of hledger’s strengths is being able to quickly report on a precise-subset of your data. Most hledger commands accept optional query-arguments to restrict their scope. The syntax is as follows:-- • Zero or more space-separated query terms. These are most often- account name substrings:-- ‘utilities food:groceries’-- • Terms with spaces or other special characters should be enclosed in- quotes:-- ‘"personal care"’-- • Regular expressions are also supported:-- ‘"^expenses\b" "accounts (payable|receivable)"’-- • Add a query type prefix to match other parts of the data:-- ‘date:202012- desc:amazon cur:USD amt:">100" status:’-- • Add a ‘not:’ prefix to negate a term:-- ‘not:cur:USD’--* Menu:--* Query types::-* Combining query terms::-* Queries and command options::-* Queries and valuation::-* Querying with account aliases::-* Querying with cost or value::---File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries--17.1 Query types-================--Here are the types of query term available. Remember these can also be-prefixed with *‘not:’* to convert them into a negative match.-- *‘acct:REGEX’, ‘REGEX’*-Match account names containing this (case insensitive) regular-expression. This is the default query type when there is no prefix, and-regular expression syntax is typically not needed, so usually we just-write an account name substring, like ‘expenses’ or ‘food’.-- *‘amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N’*-Match postings with a single-commodity amount equal to, less than, or-greater than N. (Postings with multi-commodity amounts are not tested-and will always match.) The comparison has two modes: if N is preceded-by a + or - sign (or is 0), the two signed numbers are compared.-Otherwise, the absolute magnitudes are compared, ignoring sign.-- *‘code:REGEX’*-Match by transaction code (eg check number).-- *‘cur:REGEX’*-Match postings or transactions including any amounts whose-currency/commodity symbol is fully matched by REGEX. (For a partial-match, use ‘.*REGEX.*’). Note, to match special characters which are-regex-significant, you need to escape them with ‘\’. And for characters-which are significant to your shell you may need one more level of-escaping. So eg to match the dollar sign:-‘hledger print cur:\\$’.-- *‘desc:REGEX’*-Match transaction descriptions.-- *‘date:PERIODEXPR’*-Match dates (or with the ‘--date2’ flag, secondary dates) within the-specified period. PERIODEXPR is a period expression with no report-interval. Examples:-‘date:2016’, ‘date:thismonth’, ‘date:2/1-2/15’,-‘date:2021-07-27..nextquarter’.-- *‘date2:PERIODEXPR’*-Match secondary dates within the specified period (independent of the-‘--date2’ flag).-- *‘depth:N’*-Match (or display, depending on command) accounts at or above this-depth.-- *‘note:REGEX’*-Match transaction notes (the part of the description right of ‘|’, or-the whole description if there’s no ‘|’).-- *‘payee:REGEX’*-Match transaction payee/payer names (the part of the description left of-‘|’, or the whole description if there’s no ‘|’).-- *‘real:, real:0’*-Match real or virtual postings respectively.-- *‘status:, status:!, status:*’*-Match unmarked, pending, or cleared transactions respectively.-- *‘type:TYPECODES’*-Match by account type (see Declaring accounts > Account types).-‘TYPECODES’ is one or more of the single-letter account type codes-‘ALERXCV’, case insensitive. Note ‘type:A’ and ‘type:E’ will also match-their respective subtypes ‘C’ (Cash) and ‘V’ (Conversion). Certain-kinds of account alias can disrupt account types, see Rewriting accounts-> Aliases and account types.-- *‘tag:REGEX[=REGEX]’*-Match by tag name, and optionally also by tag value. (To match only by-value, use ‘tag:.=REGEX’.)-- When querying by tag, note that:-- • Accounts also inherit the tags of their parent accounts- • Postings also inherit the tags of their account and their- transaction- • Transactions also acquire the tags of their postings.-- (*‘inacct:ACCTNAME’*-A special query term used automatically in hledger-web only: tells-hledger-web to show the transaction register for an account.)---File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries--17.2 Combining query terms-==========================--When given multiple query terms, most commands select things which-match:-- • any of the description terms AND- • any of the account terms AND- • any of the status terms AND- • all the other terms.-- The print command is a little different, showing transactions which:-- • match any of the description terms AND- • have any postings matching any of the positive account terms AND- • have no postings matching any of the negative account terms AND- • match all the other terms.-- Although these fixed rules are enough for many needs, we do not-support full boolean expressions (#203), (and you should not write AND-or OR in your queries). This makes certain queries hard to express, but-here are some tricks that can help:-- 1. Use a doubled ‘not:’ prefix. Eg, to print only the food expenses- paid with cash:-- $ hledger print food not:not:cash-- 2. Or pre-filter the transactions with ‘print’, piping the result into- a second hledger command (with balance assertions disabled):-- $ hledger print cash | hledger -f- -I balance food---File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries--17.3 Queries and command options-================================--Some queries can also be expressed as command-line options: ‘depth:2’ is-equivalent to ‘--depth 2’, ‘date:2020’ is equivalent to ‘-p 2020’, etc.-When you mix command options and query arguments, generally the-resulting query is their intersection.---File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries--17.4 Queries and valuation-==========================--When amounts are converted to other commodities in cost or value-reports, ‘cur:’ and ‘amt:’ match the old commodity symbol and the old-amount quantity, not the new ones (except in hledger 1.22.0 where it’s-reversed, see #1625).---File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries--17.5 Querying with account aliases-==================================--When account names are rewritten with ‘--alias’ or ‘alias’, note that-‘acct:’ will match either the old or the new account name.---File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries--17.6 Querying with cost or value-================================--When amounts are converted to other commodities in cost or value-reports, note that ‘cur:’ matches the new commodity symbol, and not the-old one, and ‘amt:’ matches the new quantity, and not the old one.-Note: this changed in hledger 1.22, previously it was the reverse, see-the discussion at #1625.---File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top--18 Pivoting-***********--Normally, hledger groups and sums amounts within each account. The-‘--pivot FIELD’ option substitutes some other transaction field for-account names, causing amounts to be grouped and summed by that field’s-value instead. FIELD can be any of the transaction fields ‘status’,-‘code’, ‘description’, ‘payee’, ‘note’, or a tag name. When pivoting on-a tag and a posting has multiple values of that tag, only the first-value is displayed. Values containing ‘colon:separated:parts’ will be-displayed hierarchically, like account names.-- Some examples:--2016/02/16 Yearly Dues Payment- assets:bank account 2 EUR- income:dues -2 EUR ; member: John Doe-- Normal balance report showing account names:--$ hledger balance- 2 EUR assets:bank account- -2 EUR income:dues---------------------- 0-- Pivoted balance report, using member: tag values instead:--$ hledger balance --pivot member- 2 EUR- -2 EUR John Doe---------------------- 0-- One way to show only amounts with a member: value (using a query):--$ hledger balance --pivot member tag:member=.- -2 EUR John Doe---------------------- -2 EUR-- Another way (the acct: query matches against the pivoted "account-name"):--$ hledger balance --pivot member acct:.- -2 EUR John Doe---------------------- -2 EUR---File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top--19 Generating data-******************--Two features for generating transient data (visible only at report time)-are built in to hledger’s journal format:-- • Auto posting rules can generate extra postings on certain- transactions. They are activated by the ‘--auto’ flag.-- • Periodic transaction rules can generate repeating transactions,- usually dated in the future, to help with forecasting or budgeting.- They are activated by the ‘--forecast’ or ‘balance --budget’- options, described next.---File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top--20 Forecasting-**************--The ‘--forecast’ flag activates any periodic transaction rules in the-journal. These will generate temporary additional transactions, usually-recurring and in the future, which will appear in all reports. ‘hledger-print --forecast’ is a good way to see them.-- This can be useful for estimating balances into the future, perhaps-experimenting with different scenarios.-- It could also be useful for scripted data entry: you could describe-recurring transactions, and every so often copy the output of ‘print---forecast’ into the journal.-- The generated transactions will have an extra tag, like-‘generated-transaction:~ PERIODICEXPR’, indicating which periodic rule-generated them. There is also a similar, hidden tag, named-‘_generated-transaction:’, which you can use to reliably match-transactions generated "just now" (rather than ‘print’ed in the past).-- The forecast transactions are generated within a _forecast period_,-which is independent of the report period. (Forecast period sets the-bounds for generated transactions, report period controls which-transactions are reported.) The forecast period begins on:-- • the start date provided within ‘--forecast’’s argument, if any- • otherwise, the later of- • the report start date, if specified (with ‘-b’/‘-p’/‘date:’)- • the day after the latest ordinary transaction in the journal,- if any-- • otherwise today.-- It ends on:-- • the end date provided within ‘--forecast’’s argument, if any- • otherwise, the report end date, if specified (with- ‘-e’/‘-p’/‘date:’)- • otherwise 180 days (6 months) from today.-- Note, this means that ordinary transactions will suppress periodic-transactions, by default; the periodic transactions will not start until-after the last ordinary transaction. This is usually convenient, but-you can get around it in two ways:-- • If you need to record some transactions in the future, make them- periodic transactions (with a single occurrence, eg: ‘~- YYYY-MM-DD’) rather than ordinary transactions. That way they- won’t suppress other periodic transactions.-- • Or give ‘--forecast’ a period expression argument. A forecast- period specified this way can overlap ordinary transactions, and- need not be in the future. Some things to note:-- • You must use ‘=’ between flag and argument; a space won’t- work.- • The period expression can specify the forecast period’s start- date, end date, or both. See also Report start & end date.- • The period expression should not specify a report interval.- (Each periodic transaction rule specifies its own interval.)-- Some examples: ‘--forecast=202001-202004’, ‘--forecast=jan-’,-‘--forecast=2021’.---File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top--21 Budgeting-************--With the balance command’s ‘--budget’ report, each periodic transaction-rule generates recurring budget goals in specified accounts, and goals-and actual performance can be compared. See the balance command’s doc-below.-- See also: Budgeting and Forecasting.---File: hledger.info, Node: Cost reporting, Next: Valuation, Prev: Budgeting, Up: Top--22 Cost reporting-*****************--This section is about recording the cost of things, in transactions-where one commodity is exchanged for another. Eg an exchange of-currency, or a stock purchase or sale. First, a quick glossary:-- • Conversion - an exchange of one currency or commodity for another.- Eg a foreign currency exchange, or a purchase or sale of stock or- cryptocurrency.-- • Conversion transaction - a transaction involving one or more- conversions.-- • Conversion rate - the cost per unit of one commodity in the other,- ie the exchange rate.-- • Cost - how much of one commodity was paid to acquire the other.- And more generally, in hledger docs: the amount exchanged in the- "secondary" commodity (usually your base currency), whether in a- purchase or a sale, and whether expressed per unit or in total.- Also, the "@/@@ PRICE" notation used to represent this.--* Menu:--* -B Convert to cost::-* Equity conversion postings::-* Inferring equity postings from cost::-* Inferring cost from equity postings::-* When to infer cost/equity::-* How to record conversions::-* Cost tips::---File: hledger.info, Node: -B Convert to cost, Next: Equity conversion postings, Up: Cost reporting--22.1 -B: Convert to cost-========================--As discussed in JOURNAL > Costs, when recording a transaction you can-also record the amount’s cost in another commodity, by adding ‘@-UNITPRICE’ or ‘@@ TOTALPRICE’.-- Then you can see a report with amounts converted to cost, by adding-the ‘-B/--cost’ flag. (Mnemonic: "B" from "cost Basis", as in Ledger).-Eg:--2022-01-01- assets:dollars $-135 ; 135 dollars is exchanged for..- assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each--$ hledger bal -N- $-135 assets:dollars- €100 assets:euros-$ hledger bal -N -B- $-135 assets:dollars- $135 assets:euros # <- the euros' cost-- Notes:-- -B is sensitive to the order of postings when a cost is inferred: the-inferred price will be in the commodity of the last amount. So if-example 3’s postings are reversed, while the transaction is equivalent,--B shows something different:--2022-01-01- assets:dollars $-135 ; 135 dollars sold- assets:euros €100 ; for 100 euros--$ hledger bal -N -B- €-100 assets:dollars # <- the dollars' selling price- €100 assets:euros-- The @/@@ cost notation is convenient, but has some drawbacks: it does-not truly balance the transaction, so it disrupts the accounting-equation and tends to causes a non-zero total in balance reports.---File: hledger.info, Node: Equity conversion postings, Next: Inferring equity postings from cost, Prev: -B Convert to cost, Up: Cost reporting--22.2 Equity conversion postings-===============================--By contrast, conventional double entry bookkeeping (DEB) uses a-different notation: an extra pair of equity postings to balance-conversion transactions. In this style, the above entry might be-written:--2022-01-01 one hundred euros purchased at $1.35 each- assets:dollars $-135- equity:conversion $135- equity:conversion €-100- assets:euros €100-- This style is more correct, but it’s also more verbose and makes cost-reporting more difficult for PTA tools.-- Happily, current hledger can read either notation, or convert one to-the other when needed, so you can use the one you prefer.-- You can even use cost notation and equivalent conversion postings at-the same time, for clarity. hledger will ignore the redundancy. But be-sure the cost and conversion posting amounts match, or you’ll see a-not-so-clear transaction balancing error message.---File: hledger.info, Node: Inferring equity postings from cost, Next: Inferring cost from equity postings, Prev: Equity conversion postings, Up: Cost reporting--22.3 Inferring equity postings from cost-========================================--With ‘--infer-equity’, hledger detects transactions written with PTA-cost notation and adds equity conversion postings to them:--2022-01-01- assets:dollars -$135- assets:euros €100 @ $1.35--$ hledger print --infer-equity-2022-01-01- assets:dollars $-135- assets:euros €100 @ $1.35- equity:conversion:$-€:€ €-100 ; generated-posting:- equity:conversion:$-€:$ $135.00 ; generated-posting:-- The conversion account names can be changed with the conversion-account type declaration.-- –infer-equity is useful when when transactions have been recorded-using cost notation, to help preserve the accounting equation and-balance reports’ zero total, or to produce more conventional journal-entries for sharing with non-PTA-users.---File: hledger.info, Node: Inferring cost from equity postings, Next: When to infer cost/equity, Prev: Inferring equity postings from cost, Up: Cost reporting--22.4 Inferring cost from equity postings-========================================--The reverse operation is possible using ‘--infer-costs’, which detects-transactions written with equity conversion postings and adds cost-notation to them:--2022-01-01- assets:dollars $-135- equity:conversion $135- equity:conversion €-100- assets:euros €100--$ hledger print --infer-costs-2022-01-01- assets:dollars $-135 @@ €100- equity:conversion $135- equity:conversion €-100- assets:euros €100-- –infer-costs is useful when combined with -B/–cost, allowing cost-reporting even when transactions have been recorded using equity-postings:--$ hledger print --infer-costs -B-2009-01-01- assets:dollars €-100- assets:euros €100-- Notes:-- For ‘--infer-costs’ to work, an exchange must consist of four-postings:-- 1. two non-equity postings- 2. two equity postings, next to one another- 3. the equity accounts must be declared, with account type- ‘V’/‘Conversion’ (or if they are not declared, they must be named- ‘equity:conversion’, ‘equity:trade’, ‘equity:trading’ or- subaccounts of these)- 4. the equity postings’ amounts must exactly match the non-equity- postings’ amounts.-- Multiple such exchanges can coexist within a single transaction.-- When inferring cost, the order of postings matters: the cost is added-to the first of the non-equity postings involved in the exchange, in the-commodity of the last non-equity posting involved in the exchange. If-you don’t want to write your postings in the required order, you can use-explicit cost notation instead.-- –infer-equity and –infer-costs can be used together, if you have a-mixture of both notations in your journal.---File: hledger.info, Node: When to infer cost/equity, Next: How to record conversions, Prev: Inferring cost from equity postings, Up: Cost reporting--22.5 When to infer cost/equity-==============================--Inferring equity postings or costs is still fairly new, so not enabled-by default. We’re not sure yet if that should change. Here are two-suggestions to try, experience reports welcome:-- 1. When you use -B, always use –infer-costs as well. Eg: ‘hledger bal- -B --infer-costs’-- 2. Always run hledger with both flags enabled. Eg: ‘alias hl="hledger- --infer-equity --infer-costs"’---File: hledger.info, Node: How to record conversions, Next: Cost tips, Prev: When to infer cost/equity, Up: Cost reporting--22.6 How to record conversions-==============================--Essentially there are four ways to record a conversion transaction in-hledger. Here are all of them, with pros and cons.--* Menu:--* Conversion with implicit cost::-* Conversion with explicit cost::-* Conversion with equity postings::-* Conversion with equity postings and explicit cost::---File: hledger.info, Node: Conversion with implicit cost, Next: Conversion with explicit cost, Up: How to record conversions--22.6.1 Conversion with implicit cost---------------------------------------Let’s assume 100 EUR is converted to 120 USD. You can just record the-outflow (100 EUR) and inflow (120 USD) in the appropriate asset account:--2021-01-01- assets:cash -100 EUR- assets:cash 120 USD-- hledger will assume this transaction is balanced, inferring that the-conversion rate must be 1 EUR = 1.20 USD. You can see the inferred rate-by using ‘hledger print -x’.-- Pro:-- • Concise, easy-- Con:-- • Less error checking - typos in amounts or commodity symbols may not- be detected- • Conversion rate is not clear- • Disturbs the accounting equation, unless you add the –infer-equity- flag-- You can prevent accidental implicit conversions due to a mistyped-commodity symbol, by using ‘hledger check commodities’.-- You can prevent implicit conversions entirely, by using ‘hledger-check balancednoautoconversion’, or ‘-s/--strict’.---File: hledger.info, Node: Conversion with explicit cost, Next: Conversion with equity postings, Prev: Conversion with implicit cost, Up: How to record conversions--22.6.2 Conversion with explicit cost---------------------------------------You can add the conversion rate using @ notation:--2021-01-01- assets:cash -100 EUR @ 1.20 USD- assets:cash 120 USD-- Now hledger will check that 100 * 1.20 = 120, and would report an-error otherwise.-- Pro:-- • Still concise- • Makes the conversion rate clear- • Provides more error checking-- Con:-- • Disturbs the accounting equation, unless you add the –infer-equity- flag---File: hledger.info, Node: Conversion with equity postings, Next: Conversion with equity postings and explicit cost, Prev: Conversion with explicit cost, Up: How to record conversions--22.6.3 Conversion with equity postings-----------------------------------------In strict double entry bookkeeping, the above transaction is not-balanced in EUR or in USD, since some EUR disappears, and some USD-appears. This violates the accounting equation (A+L+E=0), and prevents-reports like ‘balancesheetequity’ from showing a zero total.-- The proper way to make it balance is to add a balancing posting for-each commodity, using an equity account:--2021-01-01- assets:cash -100 EUR- equity:conversion 100 EUR- equity:conversion -120 USD- assets:cash 120 USD-- Pro:-- • Preserves the accounting equation- • Keeps track of conversions and related gains/losses in one place- • Standard, works in any double entry accounting system-- Con:-- • More verbose- • Conversion rate is not obvious- • Cost reporting requires adding the –infer-costs flag---File: hledger.info, Node: Conversion with equity postings and explicit cost, Prev: Conversion with equity postings, Up: How to record conversions--22.6.4 Conversion with equity postings and explicit cost-----------------------------------------------------------Here both equity postings and @ notation are used together.--2021-01-01- assets:cash -100 EUR @ 1.20 USD- equity:conversion 100 EUR- equity:conversion -120 USD- assets:cash 120 USD-- Pro:-- • Preserves the accounting equation- • Keeps track of conversions and related gains/losses in one place- • Makes the conversion rate clear- • Provides more error checking-- Con:-- • Most verbose- • Not compatible with ledger---File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cost reporting--22.7 Cost tips-==============-- • Recording the cost/conversion rate explicitly is good because it- makes that clear and helps detect errors.- • Recording equity postings is good because it is correct bookkeeping- and preserves the accounting equation.- • Combining these is possible.- • When you want to see the cost (or sale proceeds) of things, use- ‘-B’ (short form of ‘--cost’).- • If you use conversion postings without cost notation, add- ‘--infer-costs’ also.- • If you use cost notation without conversion postings, and you want- to see a balanced balance sheet or print correct journal entries,- use ‘--infer-equity’.- • Conversion to cost is performed before valuation (described next).---File: hledger.info, Node: Valuation, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top--23 Valuation-************--Instead of reporting amounts in their original commodity, hledger can-convert them to cost/sale amount (using the conversion rate recorded in-the transaction), and/or to market value (using some market price on a-certain date). This is controlled by the ‘--value=TYPE[,COMMODITY]’-option, which will be described below. We also provide the simpler ‘-V’-and ‘-X COMMODITY’ options, and often one of these is all you need:--* Menu:--* -V Value::-* -X Value in specified commodity::-* Valuation date::-* Finding market price::-* --infer-market-prices market prices from transactions::-* Valuation commodity::-* Simple valuation examples::-* --value Flexible valuation::-* More valuation examples::-* Interaction of valuation and queries::-* Effect of valuation on reports::---File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Valuation--23.1 -V: Value-==============--The ‘-V/--market’ flag converts amounts to market value in their default-_valuation commodity_, using the market prices in effect on the-_valuation date(s)_, if any. More on these in a minute.---File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation--23.2 -X: Value in specified commodity-=====================================--The ‘-X/--exchange=COMM’ option is like ‘-V’, except you tell it which-currency you want to convert to, and it tries to convert everything to-that.---File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Valuation--23.3 Valuation date-===================--Since market prices can change from day to day, market value reports-have a valuation date (or more than one), which determines which market-prices will be used.-- For single period reports, if an explicit report end date is-specified, that will be used as the valuation date; otherwise the-valuation date is the journal’s end date.-- For multiperiod reports, each column/period is valued on the last day-of the period, by default.---File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Valuation--23.4 Finding market price-=========================--To convert a commodity A to its market value in another commodity B,-hledger looks for a suitable market price (exchange rate) as follows, in-this order of preference :-- 1. A _declared market price_ or _inferred market price_: A’s latest- market price in B on or before the valuation date as declared by a- P directive, or (with the ‘--infer-market-prices’ flag) inferred- from costs.-- 2. A _reverse market price_: the inverse of a declared or inferred- market price from B to A.-- 3. A _forward chain of market prices_: a synthetic price formed by- combining the shortest chain of "forward" (only 1 above) market- prices, leading from A to B.-- 4. _Any chain of market prices_: a chain of any market prices,- including both forward and reverse prices (1 and 2 above), leading- from A to B.-- There is a limit to the length of these price chains; if hledger-reaches that length without finding a complete chain or exhausting all-possibilities, it will give up (with a "gave up" message visible in-‘--debug=2’ output). That limit is currently 1000.-- Amounts for which no suitable market price can be found, are not-converted.---File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Valuation--23.5 –infer-market-prices: market prices from transactions-==========================================================--Normally, market value in hledger is fully controlled by, and requires,-P directives in your journal. Since adding and updating those can be a-chore, and since transactions usually take place at close to market-value, why not use the recorded costs as additional market prices (as-Ledger does) ? Adding the ‘--infer-market-prices’ flag to ‘-V’, ‘-X’ or-‘--value’ enables this.-- So for example, ‘hledger bs -V --infer-market-prices’ will get market-prices both from P directives and from transactions. If both occur on-the same day, the P directive takes precedence.-- There is a downside: value reports can sometimes be affected in-confusing/undesired ways by your journal entries. If this happens to-you, read all of this Valuation section carefully, and try adding-‘--debug’ or ‘--debug=2’ to troubleshoot.-- ‘--infer-market-prices’ can infer market prices from:-- • multicommodity transactions with explicit prices (‘@’/‘@@’)-- • multicommodity transactions with implicit prices (no ‘@’, two- commodities, unbalanced). (With these, the order of postings- matters. ‘hledger print -x’ can be useful for troubleshooting.)-- • multicommodity transactions with equity postings, if cost is- inferred with ‘--infer-costs’.-- There is a limitation (bug) currently: when a valuation commodity is-not specified, prices inferred with ‘--infer-market-prices’ do not help-select a default valuation commodity, as ‘P’ prices would. So-conversion might not happen because no valuation commodity was detected-(‘--debug=2’ will show this). To be safe, specify the valuation-commmodity, eg:-- • ‘-X EUR --infer-market-prices’, not ‘-V --infer-market-prices’- • ‘--value=then,EUR --infer-market-prices’, not ‘--value=then- --infer-market-prices’-- Signed costs and market prices can be confusing. For reference, here-is the current behaviour, since hledger 1.25. (If you think it should-work differently, see #1870.)--2022-01-01 Positive Unit prices- a A 1- b B -1 @ A 1--2022-01-01 Positive Total prices- a A 1- b B -1 @@ A 1---2022-01-02 Negative unit prices- a A 1- b B 1 @ A -1--2022-01-02 Negative total prices- a A 1- b B 1 @@ A -1---2022-01-03 Double Negative unit prices- a A -1- b B -1 @ A -1--2022-01-03 Double Negative total prices- a A -1- b B -1 @@ A -1-- All of the transactions above are considered balanced (and on each-day, the two transactions are considered equivalent). Here are the-market prices inferred for B:--$ hledger -f- --infer-market-prices prices-P 2022-01-01 B A 1-P 2022-01-01 B A 1.0-P 2022-01-02 B A -1-P 2022-01-02 B A -1.0-P 2022-01-03 B A -1-P 2022-01-03 B A -1.0---File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Valuation--23.6 Valuation commodity-========================--*When you specify a valuation commodity (‘-X COMM’ or ‘--value-TYPE,COMM’):*-hledger will convert all amounts to COMM, wherever it can find a-suitable market price (including by reversing or chaining prices).-- *When you leave the valuation commodity unspecified (‘-V’ or ‘--value-TYPE’):*-For each commodity A, hledger picks a default valuation commodity as-follows, in this order of preference:-- 1. The price commodity from the latest P-declared market price for A- on or before valuation date.-- 2. The price commodity from the latest P-declared market price for A- on any date. (Allows conversion to proceed when there are inferred- prices before the valuation date.)-- 3. If there are no P directives at all (any commodity or date) and the- ‘--infer-market-prices’ flag is used: the price commodity from the- latest transaction-inferred price for A on or before valuation- date.-- This means:-- • If you have P directives, they determine which commodities ‘-V’- will convert, and to what.-- • If you have no P directives, and use the ‘--infer-market-prices’- flag, costs determine it.-- Amounts for which no valuation commodity can be found are not-converted.---File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation--23.7 Simple valuation examples-==============================--Here are some quick examples of ‘-V’:--; one euro is worth this many dollars from nov 1-P 2016/11/01 € $1.10--; purchase some euros on nov 3-2016/11/3- assets:euros €100- assets:checking--; the euro is worth fewer dollars by dec 21-P 2016/12/21 € $1.03-- How many euros do I have ?--$ hledger -f t.j bal -N euros- €100 assets:euros-- What are they worth at end of nov 3 ?--$ hledger -f t.j bal -N euros -V -e 2016/11/4- $110.00 assets:euros-- What are they worth after 2016/12/21 ? (no report end date-specified, defaults to today)--$ hledger -f t.j bal -N euros -V- $103.00 assets:euros---File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation--23.8 –value: Flexible valuation-===============================--‘-V’ and ‘-X’ are special cases of the more general ‘--value’ option:-- --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD.- COMM is an optional commodity symbol.- Shows amounts converted to:- - default valuation commodity (or COMM) using market prices at posting dates- - default valuation commodity (or COMM) using market prices at period end(s)- - default valuation commodity (or COMM) using current market prices- - default valuation commodity (or COMM) using market prices at some date-- The TYPE part selects cost or value and valuation date:--‘--value=then’-- Convert amounts to their value in the default valuation commodity,- using market prices on each posting’s date.-‘--value=end’-- Convert amounts to their value in the default valuation commodity,- using market prices on the last day of the report period (or if- unspecified, the journal’s end date); or in multiperiod reports,- market prices on the last day of each subperiod.-‘--value=now’-- Convert amounts to their value in the default valuation commodity- using current market prices (as of when report is generated).-‘--value=YYYY-MM-DD’-- Convert amounts to their value in the default valuation commodity- using market prices on this date.-- To select a different valuation commodity, add the optional ‘,COMM’-part: a comma, then the target commodity’s symbol. Eg:-*‘--value=now,EUR’*. hledger will do its best to convert amounts to-this commodity, deducing market prices as described above.---File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Valuation--23.9 More valuation examples-============================--Here are some examples showing the effect of ‘--value’, as seen with-‘print’:--P 2000-01-01 A 1 B-P 2000-02-01 A 2 B-P 2000-03-01 A 3 B-P 2000-04-01 A 4 B--2000-01-01- (a) 1 A @ 5 B--2000-02-01- (a) 1 A @ 6 B--2000-03-01- (a) 1 A @ 7 B-- Show the cost of each posting:--$ hledger -f- print --cost-2000-01-01- (a) 5 B--2000-02-01- (a) 6 B--2000-03-01- (a) 7 B-- Show the value as of the last day of the report period (2000-02-29):--$ hledger -f- print --value=end date:2000/01-2000/03-2000-01-01- (a) 2 B--2000-02-01- (a) 2 B-- With no report period specified, that shows the value as of the last-day of the journal (2000-03-01):--$ hledger -f- print --value=end-2000-01-01- (a) 3 B--2000-02-01- (a) 3 B--2000-03-01- (a) 3 B-- Show the current value (the 2000-04-01 price is still in effect-today):--$ hledger -f- print --value=now-2000-01-01- (a) 4 B--2000-02-01- (a) 4 B--2000-03-01- (a) 4 B-- Show the value on 2000/01/15:--$ hledger -f- print --value=2000-01-15-2000-01-01- (a) 1 B--2000-02-01- (a) 1 B--2000-03-01- (a) 1 B-- You may need to explicitly set a commodity’s display style, when-reverse prices are used. Eg this output might be surprising:--P 2000-01-01 A 2B--2000-01-01- a 1B- b--$ hledger print -x -X A-2000-01-01- a 0- b 0-- Explanation: because there’s no amount or commodity directive-specifying a display style for A, 0.5A gets the default style, which-shows no decimal digits. Because the displayed amount looks like zero,-the commodity symbol and minus sign are not displayed either. Adding a-commodity directive sets a more useful display style for A:--P 2000-01-01 A 2B-commodity 0.00A--2000-01-01- a 1B- b--$ hledger print -X A-2000-01-01- a 0.50A- b -0.50A---File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation--23.10 Interaction of valuation and queries-==========================================--When matching postings based on queries in the presence of valuation,-the following happens.-- 1. The query is separated into two parts:- 1. the currency (‘cur:’) or amount (‘amt:’).- 2. all other parts.-- 2. The postings are matched to the currency and amount queries based- on pre-valued amounts.- 3. Valuation is applied to the postings.- 4. The postings are matched to the other parts of the query based on- post-valued amounts.-- See: 1625---File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Valuation--23.11 Effect of valuation on reports-====================================--Here is a reference for how valuation is supposed to affect each part of-hledger’s reports (and a glossary). (It’s wide, you’ll have to scroll-sideways.) It may be useful when troubleshooting. If you find-problems, please report them, ideally with a reproducible example.-Related: #329, #1083.--Report ‘-B’, ‘-V’, ‘-X’ ‘--value=then’ ‘--value=end’‘--value=DATE’,-type ‘--cost’ ‘--value=now’--------------------------------------------------------------------------------*print*-posting cost value at value at posting value at value-amounts report end date report or at- or today journal DATE/today- end-balance unchanged unchanged unchanged unchanged unchanged-assertions/assignments-*register*-starting cost value at valued at day value at value-balance report or each historical report or at-(-H) journal posting was made journal DATE/today- end end-starting cost value at valued at day value at value-balance day before each historical day before at-(-H) report or posting was made report or DATE/today-with journal journal-report start start-interval-posting cost value at value at posting value at value-amounts report or date report or at- journal journal DATE/today- end end-summary summarised value at sum of postings value at value-posting cost period in interval, period at-amounts ends valued at ends DATE/today-with interval start-report-interval-running sum/average sum/average sum/average of sum/average sum/average-total/averageof of displayed values of of- displayed displayed displayed displayed- values values values values-*balance-(bs,-bse, cf,-is)*-balance sums of value at value at posting value at value-changes costs report end date report or at- or today journal DATE/today- of sums of end of of- postings sums of sums- postings of- postings-budget like like like balance like like-amounts balance balance changes balances balance-(–budget) changes changes changes-grand sum of sum of sum of displayed sum of sum of-total displayed displayed valued displayed displayed- values values values values-*balance-(bs,-bse, cf,-is) with-report-interval*-starting sums of value at sums of values value at sums-balances costs of report of postings report of-(-H) postings start of before report start of postings- before sums of start at sums of before- report all respective all report- start postings posting dates postings start- before before- report report- start start-balance sums of same as sums of values balance value-changes costs of –value=end of postings in change in at-(bal, postings period at each DATE/today-is, bs in period respective period, of-–change, posting dates valued at sums-cf period of-–change) ends postings-end sums of same as sums of values period end value-balances costs of –value=end of postings from balances, at-(bal -H, postings before period valued at DATE/today-is –H, from start to period period of-bs, cf) before end at ends sums- report respective of- start to posting dates postings- period end-budget like like like balance like like-amounts balance balance changes/end balances balance-(–budget) changes/end changes/end balances changes/end- balances balances balances-row sums, sums, sums, averages sums, sums,-totals, averages averages of displayed averages averages-row of of values of of-averages displayed displayed displayed displayed-(-T, -A) values values values values-column sums of sums of sums of sums of sums-totals displayed displayed displayed values displayed of- values values values displayed- values-grand sum, sum, sum, average of sum, sum,-total, average of average of column totals average of average-grand column column column of-average totals totals totals column- totals-- ‘--cumulative’ is omitted to save space, it works like ‘-H’ but with-a zero starting balance.-- *Glossary:*--_cost_-- calculated using price(s) recorded in the transaction(s).-_value_-- market value using available market price declarations, or the- unchanged amount if no conversion rate can be found.-_report start_-- the first day of the report period specified with -b or -p or- date:, otherwise today.-_report or journal start_-- the first day of the report period specified with -b or -p or- date:, otherwise the earliest transaction date in the journal,- otherwise today.-_report end_-- the last day of the report period specified with -e or -p or date:,- otherwise today.-_report or journal end_-- the last day of the report period specified with -e or -p or date:,- otherwise the latest transaction date in the journal, otherwise- today.-_report interval_-- a flag (-D/-W/-M/-Q/-Y) or period expression that activates the- report’s multi-period mode (whether showing one or many- subperiods).---File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Valuation, Up: Top--24 PART 4: COMMANDS-*******************--* Menu:--* Commands overview::-* accounts::-* activity::-* add::-* aregister::-* balance::-* balancesheet::-* balancesheetequity::-* cashflow::-* check::-* close::-* codes::-* commodities::-* descriptions::-* diff::-* files::-* help::-* import::-* incomestatement::-* notes::-* payees::-* prices::-* print::-* register::-* rewrite::-* roi::-* stats::-* tags::-* test::---File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS--24.1 Commands overview-======================--Here are the built-in commands:--* Menu:--* DATA ENTRY::-* DATA CREATION::-* DATA MANAGEMENT::-* REPORTS FINANCIAL::-* REPORTS VERSATILE::-* REPORTS BASIC::-* HELP::-* ADD-ONS::---File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview--24.1.1 DATA ENTRY--------------------These data entry commands are the only ones which can modify your-journal file.-- • add - add transactions using terminal prompts- • import - add new transactions from other files, eg CSV files---File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview--24.1.2 DATA CREATION----------------------- • close - generate balance-zeroing/restoring transactions- • rewrite - generate auto postings, like print –auto---File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview--24.1.3 DATA MANAGEMENT------------------------- • check - check for various kinds of error in the data- • diff - compare account transactions in two journal files---File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview--24.1.4 REPORTS, FINANCIAL---------------------------- • aregister (areg) - show transactions in a particular account- • balancesheet (bs) - show assets, liabilities and net worth- • balancesheetequity (bse) - show assets, liabilities and equity- • cashflow (cf) - show changes in liquid assets- • incomestatement (is) - show revenues and expenses---File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview--24.1.5 REPORTS, VERSATILE---------------------------- • balance (bal) - show balance changes, end balances, budgets,- gains..- • print - show transactions or export journal data- • register (reg) - show postings in one or more accounts & running- total- • roi - show return on investments---File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview--24.1.6 REPORTS, BASIC------------------------ • accounts - show account names- • activity - show bar charts of posting counts per period- • codes - show transaction codes- • commodities - show commodity/currency symbols- • descriptions - show transaction descriptions- • files - show input file paths- • notes - show note parts of transaction descriptions- • payees - show payee parts of transaction descriptions- • prices - show market prices- • stats - show journal statistics- • tags - show tag names- • test - run self tests---File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview--24.1.7 HELP-------------- • help - show the hledger manual with info/man/pager---File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview--24.1.8 ADD-ONS-----------------And here are some typical add-on commands. Some of these are installed-by the hledger-install script. If installed, they will appear in-hledger’s commands list:-- • ui - run hledger’s terminal UI- • web - run hledger’s web UI- • iadd - add transactions using a TUI (currently hard to build)- • interest - generate interest transactions- • stockquotes - download market prices from AlphaVantage- • Scripts and add-ons - check-fancyassertions, edit, fifo, git, move,- pijul, plot, and more..-- Next, each command is described in detail, in alphabetical order.---File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS--24.2 accounts-=============--Show account names.-- This command lists account names. By default it shows all known-accounts, either used in transactions or declared with account-directives.-- With query arguments, only matched account names and account names-referenced by matched postings are shown.-- Or it can show just the used accounts (‘--used’/‘-u’), the declared-accounts (‘--declared’/‘-d’), the accounts declared but not used-(‘--unused’), the accounts used but not declared (‘--undeclared’), or-the first account matched by an account name pattern, if any (‘--find’).-- It shows a flat list by default. With ‘--tree’, it uses indentation-to show the account hierarchy. In flat mode you can add ‘--drop N’ to-omit the first few account name components. Account names can be-depth-clipped with ‘depth:N’ or ‘--depth N’ or ‘-N’.-- With ‘--types’, it also shows each account’s type, if it’s known.-(See Declaring accounts > Account types.)-- With ‘--positions’, it also shows the file and line number of each-account’s declaration, if any, and the account’s overall declaration-order; these may be useful when troubleshooting account display order.-- With ‘--directives’, it adds the ‘account’ keyword, showing valid-account directives which can be pasted into a journal file. This is-useful together with ‘--undeclared’ when updating your account-declarations to satisfy ‘hledger check accounts’.-- The ‘--find’ flag can be used to look up a single account name, in-the same way that the ‘aregister’ command does. It returns the-alphanumerically-first matched account name, or if none can be found, it-fails with a non-zero exit code.-- Examples:--$ hledger accounts-assets:bank:checking-assets:bank:saving-assets:cash-expenses:food-expenses:supplies-income:gifts-income:salary-liabilities:debts--$ hledger accounts --undeclared --directives >> $LEDGER_FILE-$ hledger check accounts---File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS--24.3 activity-=============--Show an ascii barchart of posting counts per interval.-- The activity command displays an ascii histogram showing transaction-counts by day, week, month or other reporting interval (by day is the-default). With query arguments, it counts only matched transactions.-- Examples:--$ hledger activity --quarterly-2008-01-01 **-2008-04-01 *******-2008-07-01 -2008-10-01 **---File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: PART 4 COMMANDS--24.4 add-========--Prompt for transactions and add them to the journal. Any arguments will-be used as default inputs for the first N prompts.-- Many hledger users edit their journals directly with a text editor,-or generate them from CSV. For more interactive data entry, there is the-‘add’ command, which prompts interactively on the console for new-transactions, and appends them to the main journal file (which should be-in journal format). Existing transactions are not changed. This is one-of the few hledger commands that writes to the journal file (see also-‘import’).-- To use it, just run ‘hledger add’ and follow the prompts. You can-add as many transactions as you like; when you are finished, enter ‘.’-or press control-d or control-c to exit.-- Features:-- • add tries to provide useful defaults, using the most similar (by- description) recent transaction (filtered by the query, if any) as- a template.- • You can also set the initial defaults with command line arguments.- • Readline-style edit keys can be used during data entry.- • The tab key will auto-complete whenever possible - accounts,- payees/descriptions, dates (‘yesterday’, ‘today’, ‘tomorrow’). If- the input area is empty, it will insert the default value.- • If the journal defines a default commodity, it will be added to any- bare numbers entered.- • A parenthesised transaction code may be entered following a date.- • Comments and tags may be entered following a description or amount.- • If you make a mistake, enter ‘<’ at any prompt to go one step- backward.- • Input prompts are displayed in a different colour when the terminal- supports it.-- Example (see https://hledger.org/add.html for a detailed tutorial):--$ hledger add-Adding transactions to journal file /src/hledger/examples/sample.journal-Any command line arguments will be used as defaults.-Use tab key to complete, readline keys to edit, enter to accept defaults.-An optional (CODE) may follow transaction dates.-An optional ; COMMENT may follow descriptions or amounts.-If you make a mistake, enter < at any prompt to go one step backward.-To end a transaction, enter . when prompted.-To quit, enter . at a date prompt or press control-d or control-c.-Date [2015/05/22]: -Description: supermarket-Account 1: expenses:food-Amount 1: $10-Account 2: assets:checking-Amount 2 [$-10.0]: -Account 3 (or . or enter to finish this transaction): .-2015/05/22 supermarket- expenses:food $10- assets:checking $-10.0--Save this transaction to the journal ? [y]: -Saved.-Starting the next transaction (. or ctrl-D/ctrl-C to quit)-Date [2015/05/22]: <CTRL-D> $-- On Microsoft Windows, the add command makes sure that no part of the-file path ends with a period, as that would cause problems (#1056).---File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS--24.5 aregister-==============--(areg)-- Show the transactions and running historical balance of a single-account, with each transaction displayed as one line.-- ‘aregister’ shows the overall transactions affecting a particular-account (and any subaccounts). Each report line represents one-transaction in this account. Transactions before the report start date-are always included in the running balance (‘--historical’ mode is-always on).-- This is a more "real world", bank-like view than the ‘register’-command (which shows individual postings, possibly from multiple-accounts, not necessarily in historical mode). As a quick rule of-thumb: - use ‘aregister’ for reviewing and reconciling real-world-asset/liability accounts - use ‘register’ for reviewing detailed-revenues/expenses.-- ‘aregister’ requires one argument: the account to report on. You can-write either the full account name, or a case-insensitive regular-expression which will select the alphabetically first matched account.-- When there are multiple matches, the alphabetically-first choice can-be surprising; eg if you have ‘assets:per:checking 1’ and-‘assets:biz:checking 2’ accounts, ‘hledger areg checking’ would select-‘assets:biz:checking 2’. It’s just a convenience to save typing, so if-in doubt, write the full account name, or a distinctive substring that-matches uniquely.-- Transactions involving subaccounts of this account will also be-shown. ‘aregister’ ignores depth limits, so its final total will always-match a balance report with similar arguments.-- Any additional arguments form a query which will filter the-transactions shown. Note some queries will disturb the running balance,-causing it to be different from the account’s real-world running-balance.-- An example: this shows the transactions and historical running-balance during july, in the first account whose name contains-"checking":--$ hledger areg checking date:jul-- Each ‘aregister’ line item shows:-- • the transaction’s date (or the relevant posting’s date if- different, see below)- • the names of all the other account(s) involved in this transaction- (probably abbreviated)- • the total change to this account’s balance from this transaction- • the account’s historical running balance after this transaction.-- Transactions making a net change of zero are not shown by default;-add the ‘-E/--empty’ flag to show them.-- For performance reasons, column widths are chosen based on the first-1000 lines; this means unusually wide values in later lines can cause-visual discontinuities as column widths are adjusted. If you want to-ensure perfect alignment, at the cost of more time and memory, use the-‘--align-all’ flag.-- This command also supports the output destination and output format-options. The output formats supported are ‘txt’, ‘csv’, and ‘json’.--* Menu:--* aregister and custom posting dates::---File: hledger.info, Node: aregister and custom posting dates, Up: aregister--24.5.1 aregister and custom posting dates--------------------------------------------Transactions whose date is outside the report period can still be shown,-if they have a posting to this account dated inside the report period.-(And in this case it’s the posting date that is shown.) This ensures-that ‘aregister’ can show an accurate historical running balance,-matching the one shown by ‘register -H’ with the same arguments.-- To filter strictly by transaction date instead, add the ‘--txn-dates’-flag. If you use this flag and some of your postings have custom dates,-it’s probably best to assume the running balance is wrong.---File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS--24.6 balance-============--(bal)-- Show accounts and their balances.-- ‘balance’ is one of hledger’s oldest and most versatile commands, for-listing account balances, balance changes, values, value changes and-more, during one time period or many. Generally it shows a table, with-rows representing accounts, and columns representing periods.-- Note there are some higher-level variants of the ‘balance’ command-with convenient defaults, which can be simpler to use: ‘balancesheet’,-‘balancesheetequity’, ‘cashflow’ and ‘incomestatement’. When you need-more control, then use ‘balance’.--* Menu:--* balance features::-* Simple balance report::-* Balance report line format::-* Filtered balance report::-* List or tree mode::-* Depth limiting::-* Dropping top-level accounts::-* Showing declared accounts::-* Sorting by amount::-* Percentages::-* Multi-period balance report::-* Balance change end balance::-* Balance report types::-* Budget report::-* Data layout::-* Useful balance reports::---File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance--24.6.1 balance features--------------------------Here’s a quick overview of the ‘balance’ command’s features, followed by-more detailed descriptions and examples. Many of these work with the-higher-level commands as well.-- ‘balance’ can show..-- • accounts as a list (‘-l’) or a tree (‘-t’)- • optionally depth-limited (‘-[1-9]’)- • sorted by declaration order and name, or by amount-- ..and their..-- • balance changes (the default)- • or actual and planned balance changes (‘--budget’)- • or value of balance changes (‘-V’)- • or change of balance values (‘--valuechange’)- • or unrealised capital gain/loss (‘--gain’)-- ..in..-- • one time period (the whole journal period by default)- • or multiple periods (‘-D’, ‘-W’, ‘-M’, ‘-Q’, ‘-Y’, ‘-p INTERVAL’)-- ..either..-- • per period (the default)- • or accumulated since report start date (‘--cumulative’)- • or accumulated since account creation (‘--historical/-H’)-- ..possibly converted to..-- • cost (‘--value=cost[,COMM]’/‘--cost’/‘-B’)- • or market value, as of transaction dates (‘--value=then[,COMM]’)- • or at period ends (‘--value=end[,COMM]’)- • or now (‘--value=now’)- • or at some other date (‘--value=YYYY-MM-DD’)-- ..with..-- • totals (‘-T’), averages (‘-A’), percentages (‘-%’), inverted sign- (‘--invert’)- • rows and columns swapped (‘--transpose’)- • another field used as account name (‘--pivot’)- • custom-formatted line items (single-period reports only)- (‘--format’)- • commodities displayed on the same line or multiple lines- (‘--layout’)-- This command supports the output destination and output format-options, with output formats ‘txt’, ‘csv’, ‘json’, and (multi-period-reports only:) ‘html’. In ‘txt’ output in a colour-supporting terminal,-negative amounts are shown in red.-- The ‘--related’/‘-r’ flag shows the balance of the _other_ postings-in the transactions of the postings which would normally be shown.---File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance--24.6.2 Simple balance report-------------------------------With no arguments, ‘balance’ shows a list of all accounts and their-change of balance - ie, the sum of posting amounts, both inflows and-outflows - during the entire period of the journal. ("Simple" here-means just one column of numbers, covering a single period. You can-also have multi-period reports, described later.)-- For real-world accounts, these numbers will normally be their end-balance at the end of the journal period; more on this below.-- Accounts are sorted by declaration order if any, and then-alphabetically by account name. For instance (using-examples/sample.journal):--$ hledger -f examples/sample.journal bal- $1 assets:bank:saving- $-2 assets:cash- $1 expenses:food- $1 expenses:supplies- $-1 income:gifts- $-1 income:salary- $1 liabilities:debts---------------------- 0 -- Accounts with a zero balance (and no non-zero subaccounts, in tree-mode - see below) are hidden by default. Use ‘-E/--empty’ to show them-(revealing ‘assets:bank:checking’ here):--$ hledger -f examples/sample.journal bal -E- 0 assets:bank:checking- $1 assets:bank:saving- $-2 assets:cash- $1 expenses:food- $1 expenses:supplies- $-1 income:gifts- $-1 income:salary- $1 liabilities:debts---------------------- 0 -- The total of the amounts displayed is shown as the last line, unless-‘-N’/‘--no-total’ is used.---File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance--24.6.3 Balance report line format------------------------------------For single-period balance reports displayed in the terminal (only), you-can use ‘--format FMT’ to customise the format and content of each line.-Eg:--$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"- assets $-1- bank:saving $1- cash $-2- expenses $2- food $1- supplies $1- income $-2- gifts $-1- salary $-1- liabilities:debts $1----------------------------------- 0-- The FMT format string specifies the formatting applied to each-account/balance pair. It may contain any suitable text, with data-fields interpolated like so:-- ‘%[MIN][.MAX](FIELDNAME)’-- • MIN pads with spaces to at least this width (optional)-- • MAX truncates at this width (optional)-- • FIELDNAME must be enclosed in parentheses, and can be one of:-- • ‘depth_spacer’ - a number of spaces equal to the account’s- depth, or if MIN is specified, MIN * depth spaces.- • ‘account’ - the account’s name- • ‘total’ - the account’s balance/posted total, right justified-- Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:-- • ‘%_’ - render on multiple lines, bottom-aligned (the default)- • ‘%^’ - render on multiple lines, top-aligned- • ‘%,’ - render on one line, comma-separated-- There are some quirks. Eg in one-line mode, ‘%(depth_spacer)’ has no-effect, instead ‘%(account)’ has indentation built in. Experimentation-may be needed to get pleasing results.-- Some example formats:-- • ‘%(total)’ - the account’s total- • ‘%-20.20(account)’ - the account’s name, left justified, padded to- 20 characters and clipped at 20 characters- • ‘%,%-50(account) %25(total)’ - account name padded to 50- characters, total padded to 20 characters, with multiple- commodities rendered on one line- • ‘%20(total) %2(depth_spacer)%-(account)’ - the default format for- the single-column balance report---File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance--24.6.4 Filtered balance report---------------------------------You can show fewer accounts, a different time period, totals from-cleared transactions only, etc. by using query arguments or options to-limit the postings being matched. Eg:--$ hledger -f examples/sample.journal bal --cleared assets date:200806- $-2 assets:cash---------------------- $-2 ---File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance--24.6.5 List or tree mode---------------------------By default, or with ‘-l/--flat’, accounts are shown as a flat list with-their full names visible, as in the examples above.-- With ‘-t/--tree’, the account hierarchy is shown, with subaccounts’-"leaf" names indented below their parent:--$ hledger -f examples/sample.journal balance- $-1 assets- $1 bank:saving- $-2 cash- $2 expenses- $1 food- $1 supplies- $-2 income- $-1 gifts- $-1 salary- $1 liabilities:debts---------------------- 0-- Notes:-- • "Boring" accounts are combined with their subaccount for more- compact output, unless ‘--no-elide’ is used. Boring accounts have- no balance of their own and just one subaccount (eg ‘assets:bank’- and ‘liabilities’ above).-- • All balances shown are "inclusive", ie including the balances from- all subaccounts. Note this means some repetition in the output,- which requires explanation when sharing reports with- non-plaintextaccounting-users. A tree mode report’s final total is- the sum of the top-level balances shown, not of all the balances- shown.-- • Each group of sibling accounts (ie, under a common parent) is- sorted separately.---File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance--24.6.6 Depth limiting------------------------With a ‘depth:NUM’ query, or ‘--depth NUM’ option, or just ‘-NUM’ (eg:-‘-3’) balance reports will show accounts only to the specified depth,-hiding the deeper subaccounts. This can be useful for getting an-overview without too much detail.-- Account balances at the depth limit always include the balances from-any deeper subaccounts (even in list mode). Eg, limiting to depth 1:--$ hledger -f examples/sample.journal balance -1- $-1 assets- $2 expenses- $-2 income- $1 liabilities---------------------- 0 ---File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance--24.6.7 Dropping top-level accounts-------------------------------------You can also hide one or more top-level account name parts, using-‘--drop NUM’. This can be useful for hiding repetitive top-level-account names:--$ hledger -f examples/sample.journal bal expenses --drop 1- $1 food- $1 supplies---------------------- $2 ---File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance--24.6.8 Showing declared accounts-----------------------------------With ‘--declared’, accounts which have been declared with an account-directive will be included in the balance report, even if they have no-transactions. (Since they will have a zero balance, you will also need-‘-E/--empty’ to see them.)-- More precisely, _leaf_ declared accounts (with no subaccounts) will-be included, since those are usually the more useful in reports.-- The idea of this is to be able to see a useful "complete" balance-report, even when you don’t have transactions in all of your declared-accounts yet.---File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance--24.6.9 Sorting by amount---------------------------With ‘-S/--sort-amount’, accounts with the largest (most positive)-balances are shown first. Eg: ‘hledger bal expenses -MAS’ shows your-biggest averaged monthly expenses first. When more than one commodity-is present, they will be sorted by the alphabetically earliest commodity-first, and then by subsequent commodities (if an amount is missing a-commodity, it is treated as 0).-- Revenues and liability balances are typically negative, however, so-‘-S’ shows these in reverse order. To work around this, you can add-‘--invert’ to flip the signs. (Or, use one of the higher-level reports,-which flip the sign automatically. Eg: ‘hledger incomestatement -MAS’).---File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance--24.6.10 Percentages----------------------With ‘-%/--percent’, balance reports show each account’s value expressed-as a percentage of the (column) total.-- Note it is not useful to calculate percentages if the amounts in a-column have mixed signs. In this case, make a separate report for each-sign, eg:--$ hledger bal -% amt:`>0`-$ hledger bal -% amt:`<0`-- Similarly, if the amounts in a column have mixed commodities, convert-them to one commodity with ‘-B’, ‘-V’, ‘-X’ or ‘--value’, or make a-separate report for each commodity:--$ hledger bal -% cur:\\$-$ hledger bal -% cur:€---File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance--24.6.11 Multi-period balance report--------------------------------------With a report interval (set by the ‘-D/--daily’, ‘-W/--weekly’,-‘-M/--monthly’, ‘-Q/--quarterly’, ‘-Y/--yearly’, or ‘-p/--period’ flag),-‘balance’ shows a tabular report, with columns representing successive-time periods (and a title):--$ hledger -f examples/sample.journal bal --quarterly income expenses -E-Balance changes in 2008:-- || 2008q1 2008q2 2008q3 2008q4 -===================++=================================- expenses:food || 0 $1 0 0 - expenses:supplies || 0 $1 0 0 - income:gifts || 0 $-1 0 0 - income:salary || $-1 0 0 0 --------------------++---------------------------------- || $-1 $1 0 0 -- Notes:-- • The report’s start/end dates will be expanded, if necessary, to- fully encompass the displayed subperiods (so that the first and- last subperiods have the same duration as the others).- • Leading and trailing periods (columns) containing all zeroes are- not shown, unless ‘-E/--empty’ is used.- • Accounts (rows) containing all zeroes are not shown, unless- ‘-E/--empty’ is used.- • Amounts with many commodities are shown in abbreviated form, unless- ‘--no-elide’ is used. _(experimental)_- • Average and/or total columns can be added with the ‘-A/--average’- and ‘-T/--row-total’ flags.- • The ‘--transpose’ flag can be used to exchange rows and columns.- • The ‘--pivot FIELD’ option causes a different transaction field to- be used as "account name". See PIVOTING.-- Multi-period reports with many periods can be too wide for easy-viewing in the terminal. Here are some ways to handle that:-- • Hide the totals row with ‘-N/--no-total’- • Convert to a single currency with ‘-V’- • Maximize the terminal window- • Reduce the terminal’s font size- • View with a pager like less, eg: ‘hledger bal -D --color=yes | less- -RS’- • Output as CSV and use a CSV viewer like visidata (‘hledger bal -D- -O csv | vd -f csv’), Emacs’ csv-mode (‘M-x csv-mode, C-c C-a’), or- a spreadsheet (‘hledger bal -D -o a.csv && open a.csv’)- • Output as HTML and view with a browser: ‘hledger bal -D -o a.html- && open a.html’---File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance--24.6.12 Balance change, end balance--------------------------------------It’s important to be clear on the meaning of the numbers shown in-balance reports. Here is some terminology we use:-- A *_balance change_* is the net amount added to, or removed from, an-account during some period.-- An *_end balance_* is the amount accumulated in an account as of some-date (and some time, but hledger doesn’t store that; assume end of day-in your timezone). It is the sum of previous balance changes.-- We call it a *_historical end balance_* if it includes all balance-changes since the account was created. For a real world account, this-means it will match the "historical record", eg the balances reported in-your bank statements or bank web UI. (If they are correct!)-- In general, balance changes are what you want to see when reviewing-revenues and expenses, and historical end balances are what you want to-see when reviewing or reconciling asset, liability and equity accounts.-- ‘balance’ shows balance changes by default. To see accurate-historical end balances:-- 1. Initialise account starting balances with an "opening balances"- transaction (a transfer from equity to the account), unless the- journal covers the account’s full lifetime.-- 2. Include all of of the account’s prior postings in the report, by- not specifying a report start date, or by using the- ‘-H/--historical’ flag. (‘-H’ causes report start date to be- ignored when summing postings.)---File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance--24.6.13 Balance report types-------------------------------The balance command is quite flexible; here is the full detail on how to-control what it reports. If the following seems complicated, don’t-worry - this is for advanced reporting, and it does typically take some-time and experimentation to get clear on all these report modes.-- There are three important option groups:-- ‘hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]-...’--* Menu:--* Calculation type::-* Accumulation type::-* Valuation type::-* Combining balance report types::---File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types--24.6.13.1 Calculation type-..........................--The basic calculation to perform for each table cell. It is one of:-- • ‘--sum’ : sum the posting amounts (*default*)- • ‘--budget’ : sum the amounts, but also show the budget goal amount- (for each account/period)- • ‘--valuechange’ : show the change in period-end historical balance- values (caused by deposits, withdrawals, and/or market price- fluctuations)- • ‘--gain’ : show the unrealised capital gain/loss, (the current- valued balance minus each amount’s original cost)---File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types--24.6.13.2 Accumulation type-...........................--How amounts should accumulate across report periods. Another way to say-it: which time period’s postings should contribute to each cell’s-calculation. It is one of:-- • ‘--change’ : calculate with postings from column start to column- end, ie "just this column". Typically used to see- revenues/expenses. (*default for balance, incomestatement*)-- • ‘--cumulative’ : calculate with postings from report start to- column end, ie "previous columns plus this column". Typically used- to show changes accumulated since the report’s start date. Not- often used.-- • ‘--historical/-H’ : calculate with postings from journal start to- column end, ie "all postings from before report start date until- this column’s end". Typically used to see historical end balances- of assets/liabilities/equity. (*default for balancesheet,- balancesheetequity, cashflow*)---File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types--24.6.13.3 Valuation type-........................--Which kind of value or cost conversion should be applied, if any, before-displaying the report. It is one of:-- • no valuation type : don’t convert to cost or value (*default*)- • ‘--value=cost[,COMM]’ : convert amounts to cost (then optionally to- some other commodity)- • ‘--value=then[,COMM]’ : convert amounts to market value on- transaction dates- • ‘--value=end[,COMM]’ : convert amounts to market value on period- end date(s)- (*default with ‘--valuechange’, ‘--gain’*)- • ‘--value=now[,COMM]’ : convert amounts to market value on today’s- date- • ‘--value=YYYY-MM-DD[,COMM]’ : convert amounts to market value on- another date-- or one of the equivalent simpler flags:-- • ‘-B/--cost’ : like –value=cost (though, note –cost and –value are- independent options which can both be used at once)- • ‘-V/--market’ : like –value=end- • ‘-X COMM/--exchange COMM’ : like –value=end,COMM-- See Cost reporting and Valuation for more about these.---File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types--24.6.13.4 Combining balance report types-........................................--Most combinations of these options should produce reasonable reports,-but if you find any that seem wrong or misleading, let us know. The-following restrictions are applied:-- • ‘--valuechange’ implies ‘--value=end’- • ‘--valuechange’ makes ‘--change’ the default when used with the- ‘balancesheet’/‘balancesheetequity’ commands- • ‘--cumulative’ or ‘--historical’ disables ‘--row-total/-T’-- For reference, here is what the combinations of accumulation and-valuation show:--Valuation:>no valuation ‘--value= then’ ‘--value= end’ ‘--value=-Accumulation:v YYYY-MM-DD- /now’-------------------------------------------------------------------------------‘--change’change in sum of period-end DATE-value- period posting-date value of of change in- market values change in period- in period period-‘--cumulative’change from sum of period-end DATE-value- report start to posting-date value of of change- period end market values change from from report- from report report start start to- start to period to period end period end- end-‘--historicalchange from sum of period-end DATE-value-/-H’ journal start posting-date value of of change- to period end market values change from from journal- (historical end from journal journal start start to- balance) start to period to period end period end- end---File: hledger.info, Node: Budget report, Next: Data layout, Prev: Balance report types, Up: balance--24.6.14 Budget report------------------------The ‘--budget’ report type activates extra columns showing any budget-goals for each account and period. The budget goals are defined by-periodic transactions. This is useful for comparing planned and actual-income, expenses, time usage, etc.-- For example, you can take average monthly expenses in the common-expense categories to construct a minimal monthly budget:--;; Budget-~ monthly- income $2000- expenses:food $400- expenses:bus $50- expenses:movies $30- assets:bank:checking--;; Two months worth of expenses-2017-11-01- income $1950- expenses:food $396- expenses:bus $49- expenses:movies $30- expenses:supplies $20- assets:bank:checking--2017-12-01- income $2100- expenses:food $412- expenses:bus $53- expenses:gifts $100- assets:bank:checking-- You can now see a monthly budget report:--$ hledger balance -M --budget-Budget performance in 2017/11/01-2017/12/31:-- || Nov Dec -======================++====================================================- assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] -----------------------++----------------------------------------------------- || 0 [ 0] 0 [ 0] -- This is different from a normal balance report in several ways:-- • Only accounts with budget goals during the report period are shown,- by default.-- • In each column, in square brackets after the actual amount, budget- goal amounts are shown, and the actual/goal percentage. (Note:- budget goals should be in the same commodity as the actual amount.)-- • All parent accounts are always shown, even in list mode. Eg- assets, assets:bank, and expenses above.-- • Amounts always include all subaccounts, budgeted or unbudgeted,- even in list mode.-- This means that the numbers displayed will not always add up! Eg-above, the ‘expenses’ actual amount includes the gifts and supplies-transactions, but the ‘expenses:gifts’ and ‘expenses:supplies’ accounts-are not shown, as they have no budget amounts declared.-- This can be confusing. When you need to make things clearer, use the-‘-E/--empty’ flag, which will reveal all accounts including unbudgeted-ones, giving the full picture. Eg:--$ hledger balance -M --budget --empty-Budget performance in 2017/11/01-2017/12/31:-- || Nov Dec -======================++====================================================- assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:gifts || 0 $100 - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - expenses:supplies || $20 0 - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] -----------------------++----------------------------------------------------- || 0 [ 0] 0 [ 0] -- You can roll over unspent budgets to next period with ‘--cumulative’:--$ hledger balance -M --budget --cumulative-Budget performance in 2017/11/01-2017/12/31:-- || Nov Dec -======================++====================================================- assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - expenses || $495 [ 103% of $480] $1060 [ 110% of $960] - expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] - expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] - expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] - income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] -----------------------++----------------------------------------------------- || 0 [ 0] 0 [ 0] -- It’s common to limit budgets/budget reports to just expenses--hledger bal -M --budget expenses-- or just revenues and expenses (eg, using account types):--hledger bal -M --budget type:rx-- It’s also common to limit or convert them to a single currency-(‘cur:COMM’ or ‘-X COMM [--infer-market-prices]’). If showing multiple-currencies, ‘--layout bare’ or ‘--layout tall’ can help.-- For more examples and notes, see Budgeting.--* Menu:--* Budget report start date::-* Budgets and subaccounts::-* Selecting budget goals::-* Budget vs forecast::---File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report--24.6.14.1 Budget report start date-..................................--This might be a bug, but for now: when making budget reports, it’s a-good idea to explicitly set the report’s start date to the first day of-a reporting period, because a periodic rule like ‘~ monthly’ generates-its transactions on the 1st of each month, and if your journal has no-regular transactions on the 1st, the default report start date could-exclude that budget goal, which can be a little surprising. Eg here the-default report period is just the day of 2020-01-15:--~ monthly in 2020- (expenses:food) $500--2020-01-15- expenses:food $400- assets:checking--$ hledger bal expenses --budget-Budget performance in 2020-01-15:-- || 2020-01-15 -==============++============- <unbudgeted> || $400 ---------------++------------- || $400 -- To avoid this, specify the budget report’s period, or at least the-start date, with ‘-b’/‘-e’/‘-p’/‘date:’, to ensure it includes the-budget goal transactions (periodic transactions) that you want. Eg,-adding ‘-b 2020/1/1’ to the above:--$ hledger bal expenses --budget -b 2020/1/1-Budget performance in 2020-01-01..2020-01-15:-- || 2020-01-01..2020-01-15 -===============++========================- expenses:food || $400 [80% of $500] ----------------++------------------------- || $400 [80% of $500] ---File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report--24.6.14.2 Budgets and subaccounts-.................................--You can add budgets to any account in your account hierarchy. If you-have budgets on both parent account and some of its children, then-budget(s) of the child account(s) would be added to the budget of their-parent, much like account balances behave.-- In the most simple case this means that once you add a budget to any-account, all its parents would have budget as well.-- To illustrate this, consider the following budget:--~ monthly from 2019/01- expenses:personal $1,000.00- expenses:personal:electronics $100.00- liabilities-- With this, monthly budget for electronics is defined to be $100 and-budget for personal expenses is an additional $1000, which implicitly-means that budget for both ‘expenses:personal’ and ‘expenses’ is $1100.-- Transactions in ‘expenses:personal:electronics’ will be counted both-towards its $100 budget and $1100 of ‘expenses:personal’ , and-transactions in any other subaccount of ‘expenses:personal’ would be-counted towards only towards the budget of ‘expenses:personal’.-- For example, let’s consider these transactions:--~ monthly from 2019/01- expenses:personal $1,000.00- expenses:personal:electronics $100.00- liabilities--2019/01/01 Google home hub- expenses:personal:electronics $90.00- liabilities $-90.00--2019/01/02 Phone screen protector- expenses:personal:electronics:upgrades $10.00- liabilities--2019/01/02 Weekly train ticket- expenses:personal:train tickets $153.00- liabilities--2019/01/03 Flowers- expenses:personal $30.00- liabilities-- As you can see, we have transactions in-‘expenses:personal:electronics:upgrades’ and ‘expenses:personal:train-tickets’, and since both of these accounts are without explicitly-defined budget, these transactions would be counted towards budgets of-‘expenses:personal:electronics’ and ‘expenses:personal’ accordingly:--$ hledger balance --budget -M-Budget performance in 2019/01:-- || Jan -===============================++===============================- expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - liabilities || $-283.00 [ 26% of $-1100.00] --------------------------------++-------------------------------- || 0 [ 0] -- And with ‘--empty’, we can get a better picture of budget allocation-and consumption:--$ hledger balance --budget -M --empty-Budget performance in 2019/01:-- || Jan -========================================++===============================- expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - expenses:personal:electronics:upgrades || $10.00 - expenses:personal:train tickets || $153.00 - liabilities || $-283.00 [ 26% of $-1100.00] -----------------------------------------++-------------------------------- || 0 [ 0] ---File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report--24.6.14.3 Selecting budget goals-................................--The budget report evaluates periodic transaction rules to generate-special "goal transactions", which generate the goal amounts for each-account in each report subperiod. When troubleshooting, you can use-‘print --forecast’ to show these as forecasted transactions:--$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated-- By default, the budget report uses all available periodic transaction-rules to generate goals. This includes rules with a different report-interval from your report. Eg if you have daily, weekly and monthly-periodic rules, all of these will contribute to the goals in a monthly-budget report.-- You can select a subset of periodic rules by providing an argument to-the ‘--budget’ flag. ‘--budget=DESCPAT’ will match all periodic rules-whose description contains DESCPAT, a case-insensitive substring (not a-regular expression or query). This means you can give your periodic-rules descriptions (remember that two spaces are needed), and then-select from multiple budgets defined in your journal.---File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report--24.6.14.4 Budget vs forecast-............................--‘hledger --forecast ...’ and ‘hledger balance --budget ...’ are separate-features, though both of them use the periodic transaction rules defined-in the journal, and both of them generate temporary transactions for-reporting purposes ("forecast transactions" and "budget goal-transactions", respectively). You can use both features at the same-time if you want. Here are some differences between them, as of hledger-1.29:-- CLI:-- • –forecast is a general hledger option, usable with any command- • –budget is a ‘balance’ command option, usable only with that- command.-- Visibility of generated transactions:-- • forecast transactions are visible in any report, like ordinary- transactions- • budget goal transactions are invisible except for the goal amounts- they produce in –budget reports.-- Periodic transaction rules:-- • –forecast uses all available periodic transaction rules- • –budget uses all periodic rules (‘--budget’) or a selected subset- (‘--budget=DESCPAT’)-- Period of generated transactions:-- • –forecast generates forecast transactions- • from after the last regular transaction to the end of the- report period (‘--forecast’)- • or, during a specified period (‘--forecast=PERIODEXPR’)- • possibly further restricted by a period specified in the- periodic transaction rule- • and always restricted within the bounds of the report period-- • –budget generates budget goal transactions- • throughout the report period- • possibly restricted by a period specified in the periodic- transaction rule.---File: hledger.info, Node: Data layout, Next: Useful balance reports, Prev: Budget report, Up: balance--24.6.15 Data layout----------------------The ‘--layout’ option affects how balance reports show multi-commodity-amounts and commodity symbols, which can improve readability. It can-also normalise the data for easy consumption by other programs. It has-four possible values:-- • ‘--layout=wide[,WIDTH]’: commodities are shown on a single line,- optionally elided to WIDTH- • ‘--layout=tall’: each commodity is shown on a separate line- • ‘--layout=bare’: commodity symbols are in their own column, amounts- are bare numbers- • ‘--layout=tidy’: data is normalised to easily-consumed "tidy" form,- with one row per data value-- Here are the ‘--layout’ modes supported by each output format; note-only CSV output supports all of them:--- txt csv html json sql-----------------------------------------wide Y Y Y-tall Y Y Y-bare Y Y Y-tidy Y-- Examples:-- • Wide layout. With many commodities, reports can be very wide:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide- Balance changes in 2012-01-01..2014-12-31:- - || 2012 2013 2014 Total - ==================++====================================================================================================================================================================================================================- Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT -- • Limited wide layout. A width limit reduces the width, but some- commodities will be hidden:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32- Balance changes in 2012-01-01..2014-12-31:- - || 2012 2013 2014 Total - ==================++===========================================================================================================================- Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++---------------------------------------------------------------------------------------------------------------------------- || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. -- • Tall layout. Each commodity gets a new line (may be different in- each column), and account names are repeated:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall- Balance changes in 2012-01-01..2014-12-31:- - || 2012 2013 2014 Total - ==================++==================================================- Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++--------------------------------------------------- || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT -- • Bare layout. Commodity symbols are kept in one column, each- commodity gets its own report row, account names are repeated:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare- Balance changes in 2012-01-01..2014-12-31:- - || Commodity 2012 2013 2014 Total - ==================++=============================================- Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++---------------------------------------------- || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 -- • Bare layout also affects CSV output, which is useful for producing- data that is easier to consume, eg for making charts:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare- "account","commodity","balance"- "Assets:US:ETrade","GLD","70.00"- "Assets:US:ETrade","ITOT","17.00"- "Assets:US:ETrade","USD","5120.50"- "Assets:US:ETrade","VEA","36.00"- "Assets:US:ETrade","VHT","294.00"- "total","GLD","70.00"- "total","ITOT","17.00"- "total","USD","5120.50"- "total","VEA","36.00"- "total","VHT","294.00"-- • Tidy layout produces normalised "tidy data", where every variable- has its own column and each row represents a single data point.- See- https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html- for more. This is the easiest kind of data for other software to- consume. Here’s how it looks:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy- "account","period","start_date","end_date","commodity","value"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"---File: hledger.info, Node: Useful balance reports, Prev: Data layout, Up: balance--24.6.16 Useful balance reports---------------------------------Some frequently used ‘balance’ options/reports are:-- • ‘bal -M revenues expenses’- Show revenues/expenses in each month. Also available as the- ‘incomestatement’ command.-- • ‘bal -M -H assets liabilities’- Show historical asset/liability balances at each month end. Also- available as the ‘balancesheet’ command.-- • ‘bal -M -H assets liabilities equity’- Show historical asset/liability/equity balances at each month end.- Also available as the ‘balancesheetequity’ command.-- • ‘bal -M assets not:receivable’- Show changes to liquid assets in each month. Also available as the- ‘cashflow’ command.-- Also:-- • ‘bal -M expenses -2 -SA’- Show monthly expenses summarised to depth 2 and sorted by average- amount.-- • ‘bal -M --budget expenses’- Show monthly expenses and budget goals.-- • ‘bal -M --valuechange investments’- Show monthly change in market value of investment assets.-- • ‘bal investments --valuechange -D date:lastweek amt:'>1000' -STA- [--invert]’- Show top gainers [or losers] last week---File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS--24.7 balancesheet-=================--(bs)-- This command displays a balance sheet, showing historical ending-balances of asset and liability accounts. (To see equity as well, use-the balancesheetequity command.) Amounts are shown with normal positive-sign, as in conventional financial statements.-- This report shows accounts declared with the ‘Asset’, ‘Cash’ or-‘Liability’ type (see account types). Or if no such accounts are-declared, it shows top-level accounts named ‘asset’ or ‘liability’ (case-insensitive, plurals allowed) and their subaccounts.-- Example:--$ hledger balancesheet-Balance Sheet--Assets:- $-1 assets- $1 bank:saving- $-2 cash---------------------- $-1--Liabilities:- $1 liabilities:debts---------------------- $1--Total:---------------------- 0-- This command is a higher-level variant of the ‘balance’ command, and-supports many of that command’s features, such as multi-period reports.-It is similar to ‘hledger balance -H assets liabilities’, but with-smarter account detection, and liabilities displayed with their sign-flipped.-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, ‘html’, and-(experimental) ‘json’.---File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS--24.8 balancesheetequity-=======================--(bse)-- This command displays a balance sheet, showing historical ending-balances of asset, liability and equity accounts. Amounts are shown-with normal positive sign, as in conventional financial statements.-- This report shows accounts declared with the ‘Asset’, ‘Cash’,-‘Liability’ or ‘Equity’ type (see account types). Or if no such-accounts are declared, it shows top-level accounts named ‘asset’,-‘liability’ or ‘equity’ (case insensitive, plurals allowed) and their-subaccounts.-- Example:--$ hledger balancesheetequity-Balance Sheet With Equity--Assets:- $-2 assets- $1 bank:saving- $-3 cash---------------------- $-2--Liabilities:- $1 liabilities:debts---------------------- $1--Equity:- $1 equity:owner---------------------- $1--Total:---------------------- 0-- This command is a higher-level variant of the ‘balance’ command, and-supports many of that command’s features, such as multi-period reports.-It is similar to ‘hledger balance -H assets liabilities equity’, but-with smarter account detection, and liabilities/equity displayed with-their sign flipped.-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, ‘html’, and-(experimental) ‘json’.---File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS--24.9 cashflow-=============--(cf)-- This command displays a cashflow statement, showing the inflows and-outflows affecting "cash" (ie, liquid, easily convertible) assets.-Amounts are shown with normal positive sign, as in conventional-financial statements.-- This report shows accounts declared with the ‘Cash’ type (see account-types). Or if no such accounts are declared, it shows accounts-- • under a top-level account named ‘asset’ (case insensitive, plural- allowed)- • whose name contains some variation of ‘cash’, ‘bank’, ‘checking’ or- ‘saving’.-- More precisely: all accounts matching this case insensitive regular-expression:-- ‘^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)’-- and their subaccounts.-- An example cashflow report:--$ hledger cashflow-Cashflow Statement--Cash flows:- $-1 assets- $1 bank:saving- $-2 cash---------------------- $-1--Total:---------------------- $-1-- This command is a higher-level variant of the ‘balance’ command, and-supports many of that command’s features, such as multi-period reports.-It is similar to ‘hledger balance assets not:fixed not:investment-not:receivable’, but with smarter account detection.-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, ‘html’, and-(experimental) ‘json’.---File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS--24.10 check-===========--Check for various kinds of errors in your data.-- hledger provides a number of built-in error checks to help prevent-problems in your data. Some of these are run automatically; or, you can-use this ‘check’ command to run them on demand, with no output and a-zero exit code if all is well. Specify their names (or a prefix) as-argument(s).-- Some examples:--hledger check # basic checks-hledger check -s # basic + strict checks-hledger check ordereddates payees # basic + two other checks-- If you are an Emacs user, you can also configure flycheck-hledger to-run these checks, providing instant feedback as you edit the journal.-- Here are the checks currently available:--* Menu:--* Basic checks::-* Strict checks::-* Other checks::-* Custom checks::-* More about specific checks::---File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check--24.10.1 Basic checks-----------------------These checks are always run automatically, by (almost) all hledger-commands, including ‘check’:-- • *parseable* - data files are well-formed and can be successfully- parsed-- • *balancedwithautoconversion* - all transactions are balanced,- inferring missing amounts where necessary, and possibly converting- commodities using costs or automatically-inferred costs-- • *assertions* - all balance assertions in the journal are passing.- (This check can be disabled with ‘-I’/‘--ignore-assertions’.)---File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check--24.10.2 Strict checks------------------------These additional checks are run when the ‘-s’/‘--strict’ (strict mode)-flag is used. Or, they can be run by giving their names as arguments to-‘check’:-- • *accounts* - all account names used by transactions have been- declared-- • *commodities* - all commodity symbols used have been declared-- • *balancednoautoconversion* - transactions are balanced, possibly- using explicit costs but not inferred ones---File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check--24.10.3 Other checks-----------------------These checks can be run only by giving their names as arguments to-‘check’. They are more specialised and not desirable for everyone,-therefore optional:-- • *ordereddates* - transactions are ordered by date within each file-- • *payees* - all payees used by transactions have been declared-- • *recentassertions* - all accounts with balance assertions have a- balance assertion no more than 7 days before their latest posting-- • *tags* - all tags used by transactions have been declared-- • *uniqueleafnames* - all account leaf names are unique---File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check--24.10.4 Custom checks------------------------A few more checks are are available as separate add-on commands, in-https://github.com/simonmichael/hledger/tree/master/bin:-- • *hledger-check-tagfiles* - all tag values containing / (a forward- slash) exist as file paths-- • *hledger-check-fancyassertions* - more complex balance assertions- are passing-- You could make similar scripts to perform your own custom checks.-See: Cookbook -> Scripting.---File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check--24.10.5 More about specific checks-------------------------------------‘hledger check recentassertions’ will complain if any balance-asserted-account does not have a balance assertion within 7 days before its-latest posting. This aims to prevent the situation where you are-regularly updating your journal, but forgetting to check your balances-against the real world, then one day must dig back through months of-data to find an error. It assumes that adding a balance assertion-requires/reminds you to check the real-world balance. That may not be-true if you auto-generate balance assertions from bank data; in that-case, I recommend to import transactions uncleared, then use the-manual-review-and-mark-cleared phase as a reminder to check the latest-assertions against real-world balances.---File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS--24.11 close-===========--‘close [--retain | --migrate | --open] [QUERY]’-- By default: prints a transaction that zeroes out ("closes") all-accounts, transferring their balances to an equity account. Query-arguments can be added to override the accounts selection. Three other-modes are supported:-- ‘--retain’: prints a transaction closing revenue and expense-balances. This is traditionally done by businesses at the end of each-accounting period; it is less necessary in personal and computer-based-accounting, but it can help balance the accounting equation A=L+E.-- ‘--migrate’: prints a transaction to close asset, liability and most-equity balances, and another transaction to re-open them. This can be-useful when starting a new file (for performance or data protection).-Adding the closing transaction to the old file allows old and new files-to be combined.-- ‘--open’: as above, but prints just the opening transaction. This-can be useful for starting a new file, leaving the old file unchanged.-Similar to Ledger’s equity command.-- You can change the equity account name with ‘--close-acct ACCT’. It-defaults to ‘equity:retained earnings’ with ‘--retain’, or-‘equity:opening/closing balances’ otherwise.-- You can change the transaction description(s) with ‘--close-desc-'DESC'’ and ‘--open-desc 'DESC'’. It defaults to ‘retain earnings’ with-‘--retain’, or ‘closing balances’ and ‘opening balances’ otherwise.-- Just one posting to the equity account will be used by default, with-an implicit amount.-- With ‘--x/--explicit’ the amount will be shown explicitly, and if it-involves multiple commodities, a separate posting will be generated for-each commodity.-- With ‘--interleaved’, each equity posting is shown next to the-corresponding source/destination posting.-- The default closing date is yesterday or the journal’s end date,-whichever is later. You can change this by specifying a report end-date; the last day of the report period will be the closing date. Eg-‘-e 2022’ means "close on 2022-12-31".-- The default closing date is yesterday, or the journal’s end date,-whichever is later. You can change this by specifying a report end-date; (The report start date does not matter.) The last day of the-report period will be the closing date; eg ‘-e 2022’ means "close on-2022-12-31". The opening date is always the day after the closing date.--* Menu:--* close and costs::-* close and balance assertions::-* Example retain earnings::-* Example migrate balances to a new file::-* Example excluding closing/opening transactions::---File: hledger.info, Node: close and costs, Next: close and balance assertions, Up: close--24.11.1 close and costs--------------------------With ‘--show-costs’, any amount costs are shown, with separate postings-for each cost. (This currently the best way to view investment assets,-showing lots and cost bases.) If you have many currency conversion or-investment transactions, it can generate very large journal entries.---File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Prev: close and costs, Up: close--24.11.2 close and balance assertions---------------------------------------Balance assertions will be generated, verifying that the accounts have-been reset to zero (and then restored to their previous balances, if-there is an opening transaction).-- These provide useful error checking, but you can ignore them-temporarily with ‘-I’, or remove them if you prefer.-- You probably should avoid filtering transactions by status or-realness (‘-C’, ‘-R’, ‘status:’), or generating postings (‘--auto’),-with this command, since the balance assertions would depend on these.-- Note custom posting dates spanning the file boundary will disrupt the-balance assertions:--2023-12-30 a purchase made in december, cleared in january- expenses:food 5- assets:bank:checking -5 ; date: 2023-01-02-- To solve that you can transfer the money to and from a temporary-account, in effect splitting the multi-day transaction into two-single-day transactions:--; in 2022.journal:-2022-12-30 a purchase made in december, cleared in january- expenses:food 5- equity:pending -5--; in 2023.journal:-2023-01-02 last year's transaction cleared- equity:pending 5 = 0- assets:bank:checking -5---File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close--24.11.3 Example: retain earnings-----------------------------------Record 2022’s revenues/expenses as retained earnings on 2022-12-31,-appending the generated transaction to the journal:--$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal-- Now 2022’s income statement will show only zeroes. To see it again,-exclude the retain transaction. Eg:--$ hledger -f 2022.journal is not:desc:'retain earnings'---File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close--24.11.4 Example: migrate balances to a new file--------------------------------------------------Close assets/liabilities/equity on 2022-12-31 and re-open them on-2023-01-01:--$ hledger close --migrate -f 2022.journal -p 2022-# copy/paste the closing transaction to the end of 2022.journal-# copy/paste the opening transaction to the start of 2023.journal-- Now 2022’s balance sheet will show only zeroes, indicating a balanced-accounting equation. (Unless you are using @/@@ notation - in that-case, try adding –infer-equity.) To see it again, exclude the closing-transaction. Eg:--$ hledger -f 2022.journal bs not:desc:'closing balances'---File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close--24.11.5 Example: excluding closing/opening transactions----------------------------------------------------------When combining many files for multi-year reports, the closing/opening-transactions cause some noise in reports like ‘print’ and ‘register’.-You can exclude them as shown above, but ‘not:desc:...’ could be-fragile, and also you will need to avoid excluding the very first-opening transaction, which can be awkward. Here is a way to do it,-using tags: add ‘clopen:’ tags to all opening/closing balances-transactions except the first, like this:--; 2021.journal-2021-06-01 first opening balances-...-2021-12-31 closing balances ; clopen:2022-...--; 2022.journal-2022-01-01 opening balances ; clopen:2022-...-2022-12-31 closing balances ; clopen:2023-...--; 2023.journal-2023-01-01 opening balances ; clopen:2023-...-- Now, assuming a combined journal like:--; all.journal-include 2021.journal-include 2022.journal-include 2023.journal-- The ‘clopen:’ tag can exclude all but the first opening transaction.-To show a clean multi-year checking register:--$ hledger -f all.journal areg checking not:tag:clopen-- And the year values allow more precision. To show 2022’s year-end-balance sheet:--$ hledger -f all.journal bs -e2023 not:tag:clopen=2023---File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS--24.12 codes-===========--List the codes seen in transactions, in the order parsed.-- This command prints the value of each transaction’s code field, in-the order transactions were parsed. The transaction code is an optional-value written in parentheses between the date and description, often-used to store a cheque number, order number or similar.-- Transactions aren’t required to have a code, and missing or empty-codes will not be shown by default. With the ‘-E’/‘--empty’ flag, they-will be printed as blank lines.-- You can add a query to select a subset of transactions.-- Examples:--2022/1/1 (123) Supermarket - Food $5.00- Checking --2022/1/2 (124) Post Office- Postage $8.32- Checking--2022/1/3 Supermarket- Food $11.23- Checking --2022/1/4 (126) Post Office- Postage $3.21- Checking--$ hledger codes-123-124-126--$ hledger codes -E-123-124--126---File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: PART 4 COMMANDS--24.13 commodities-=================--List all commodity/currency symbols used or declared in the journal.---File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: PART 4 COMMANDS--24.14 descriptions-==================--List the unique descriptions that appear in transactions.-- This command lists the unique descriptions that appear in-transactions, in alphabetic order. You can add a query to select a-subset of transactions.-- Example:--$ hledger descriptions-Store Name-Gas Station | Petrol-Person A---File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS--24.15 diff-==========--Compares a particular account’s transactions in two input files. It-shows any transactions to this account which are in one file but not in-the other.-- More precisely, for each posting affecting this account in either-file, it looks for a corresponding posting in the other file which posts-the same amount to the same account (ignoring date, description, etc.)-Since postings not transactions are compared, this also works when-multiple bank transactions have been combined into a single journal-entry.-- This is useful eg if you have downloaded an account’s transactions-from your bank (eg as CSV data). When hledger and your bank disagree-about the account balance, you can compare the bank data with your-journal to find out the cause.-- Examples:--$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only:--2014/01/01 Opening Balances- assets:bank:giro EUR ...- ...- equity:opening balances EUR -...--These transactions are in the second file only:---File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS--24.16 files-===========--List all files included in the journal. With a REGEX argument, only-file names matching the regular expression (case sensitive) are shown.---File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS--24.17 help-==========--Show the hledger user manual in the terminal, with ‘info’, ‘man’, or a-pager. With a TOPIC argument, open it at that topic if possible. TOPIC-can be any heading in the manual, or a heading prefix, case insensitive.-Eg: ‘commands’, ‘print’, ‘forecast’, ‘journal’, ‘amount’, ‘"auto-postings"’.-- This command shows the hledger manual built in to your hledger-version. It can be useful when offline, or when you prefer the terminal-to a web browser, or when the appropriate hledger manual or viewing-tools are not installed on your system.-- By default it chooses the best viewer found in $PATH (preferring info-since the hledger manual is large). You can select a particular viewer-with the ‘-i’, ‘-m’, or ‘-p’ flags.-- Examples--$ hledger help --help # show how the help command works-$ hledger help # show the hledger manual with info, man or $PAGER-$ hledger help journal # show the journal topic in the hledger manual---File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS--24.18 import-============--Read new transactions added to each FILE since last run, and add them to-the journal. Or with –dry-run, just print the transactions that would-be added. Or with –catchup, just mark all of the FILEs’ transactions as-imported, without actually importing any.-- This command may append new transactions to the main journal file-(which should be in journal format). Existing transactions are not-changed. This is one of the few hledger commands that writes to the-journal file (see also ‘add’).-- Unlike other hledger commands, with ‘import’ the journal file is an-output file, and will be modified, though only by appending (existing-data will not be changed). The input files are specified as arguments,-so to import one or more CSV files to your main journal, you will run-‘hledger import bank.csv’ or perhaps ‘hledger import *.csv’.-- Note you can import from any file format, though CSV files are the-most common import source, and these docs focus on that case.--* Menu:--* Deduplication::-* Import testing::-* Importing balance assignments::-* Commodity display styles::---File: hledger.info, Node: Deduplication, Next: Import testing, Up: import--24.18.1 Deduplication------------------------As a convenience ‘import’ does _deduplication_ while reading-transactions. This does not mean "ignore transactions that look the-same", but rather "ignore transactions that have been seen before".-This is intended for when you are periodically importing foreign data-which may contain already-imported transactions. So eg, if every day-you download bank CSV files containing redundant data, you can safely-run ‘hledger import bank.csv’ and only new transactions will be-imported. (‘import’ is idempotent.)-- Since the items being read (CSV records, eg) often do not come with-unique identifiers, hledger detects new transactions by date, assuming-that:-- 1. new items always have the newest dates- 2. item dates do not change across reads- 3. and items with the same date remain in the same relative order- across reads.-- These are often true of CSV files representing transactions, or true-enough so that it works pretty well in practice. 1 is important, but-violations of 2 and 3 amongst the old transactions won’t matter (and if-you import often, the new transactions will be few, so less likely to be-the ones affected).-- hledger remembers the latest date processed in each input file by-saving a hidden ".latest" state file in the same directory. Eg when-reading ‘finance/bank.csv’, it will look for and update the-‘finance/.latest.bank.csv’ state file. The format is simple: one or-more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I-have processed transactions up to this date, and this many of them on-that date." Normally you won’t see or manipulate these state files-yourself. But if needed, you can delete them to reset the state (making-all transactions "new"), or you can construct them to "catch up" to a-certain date.-- Note deduplication (and updating of state files) can also be done by-‘print --new’, but this is less often used.---File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import--24.18.2 Import testing-------------------------With ‘--dry-run’, the transactions that will be imported are printed to-the terminal, without updating your journal or state files. The output-is valid journal format, like the print command, so you can re-parse it.-Eg, to see any importable transactions which CSV rules have not-categorised:--$ hledger import --dry bank.csv | hledger -f- -I print unknown-- or (live updating):--$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'-- Note: when importing from multiple files at once, it’s currently-possible for some .latest files to be updated successfully, while the-actual import fails because of a problem in one of the files, leaving-them out of sync (and causing some transactions to be missed). To-prevent this, do a –dry-run first and fix any problems before the real-import.---File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import--24.18.3 Importing balance assignments----------------------------------------Entries added by import will have their posting amounts made explicit-(like ‘hledger print -x’). This means that any balance assignments in-imported files must be evaluated; but, imported files don’t get to see-the main file’s account balances. As a result, importing entries with-balance assignments (eg from an institution that provides only balances-and not posting amounts) will probably generate incorrect posting-amounts. To avoid this problem, use print instead of import:--$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE-- (If you think import should leave amounts implicit like print does,-please test it and send a pull request.)---File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import--24.18.4 Commodity display styles-----------------------------------Imported amounts will be formatted according to the canonical commodity-styles (declared or inferred) in the main journal file.---File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS--24.19 incomestatement-=====================--(is)-- This command displays an income statement, showing revenues and-expenses during one or more periods. Amounts are shown with normal-positive sign, as in conventional financial statements.-- This report shows accounts declared with the ‘Revenue’ or ‘Expense’-type (see account types). Or if no such accounts are declared, it shows-top-level accounts named ‘revenue’ or ‘income’ or ‘expense’ (case-insensitive, plurals allowed) and their subaccounts.-- Example:--$ hledger incomestatement-Income Statement--Revenues:- $-2 income- $-1 gifts- $-1 salary---------------------- $-2--Expenses:- $2 expenses- $1 food- $1 supplies---------------------- $2--Total:---------------------- 0-- This command is a higher-level variant of the ‘balance’ command, and-supports many of that command’s features, such as multi-period reports.-It is similar to ‘hledger balance '(revenues|income)' expenses’, but-with smarter account detection, and revenues/income displayed with their-sign flipped.-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, ‘html’, and-(experimental) ‘json’.---File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS--24.20 notes-===========--List the unique notes that appear in transactions.-- This command lists the unique notes that appear in transactions, in-alphabetic order. You can add a query to select a subset of-transactions. The note is the part of the transaction description after-a | character (or if there is no |, the whole description).-- Example:--$ hledger notes-Petrol-Snacks---File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS--24.21 payees-============--List the unique payee/payer names that appear in transactions.-- This command lists unique payee/payer names which have been declared-with payee directives (–declared), used in transaction descriptions-(–used), or both (the default).-- The payee/payer is the part of the transaction description before a |-character (or if there is no |, the whole description).-- You can add query arguments to select a subset of transactions. This-implies –used.-- Example:--$ hledger payees-Store Name-Gas Station-Person A---File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS--24.22 prices-============--Print market price directives from the journal. With-–infer-market-prices, generate additional market prices from costs.-With –infer-reverse-prices, also generate market prices by inverting-known prices. Prices can be filtered by a query. Price amounts are-displayed with their full precision.---File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS--24.23 print-===========--Show transaction journal entries, sorted by date.-- The print command displays full journal entries (transactions) from-the journal file, sorted by date (or with ‘--date2’, by secondary date).-- Amounts are shown mostly normalised to commodity display style, eg-the placement of commodity symbols will be consistent. All of their-decimal places are shown, as in the original journal entry (with one-alteration: in some cases trailing zeroes are added.)-- Amounts are shown right-aligned within each transaction (but not-across all transactions).-- Directives and inter-transaction comments are not shown, currently.-This means the print command is somewhat lossy, and if you are using it-to reformat your journal you should take care to also copy over the-directives and file-level comments.-- Eg:--$ hledger print-2008/01/01 income- assets:bank:checking $1- income:salary $-1--2008/06/01 gift- assets:bank:checking $1- income:gifts $-1--2008/06/02 save- assets:bank:saving $1- assets:bank:checking $-1--2008/06/03 * eat & shop- expenses:food $1- expenses:supplies $1- assets:cash $-2--2008/12/31 * pay off- liabilities:debts $1- assets:bank:checking $-1-- print’s output is usually a valid hledger journal, and you can-process it again with a second hledger command. This can be useful for-certain kinds of search, eg:--# Show running total of food expenses paid from cash.-# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.-$ hledger print assets:cash | hledger -f- -I reg expenses:food-- There are some situations where print’s output can become-unparseable:-- • Valuation affects posting amounts but not balance assertion or- balance assignment amounts, potentially causing those to fail.- • Auto postings can generate postings with too many missing amounts.- • Account aliases can generate bad account names.-- Normally, the journal entry’s explicit or implicit amount style is-preserved. For example, when an amount is omitted in the journal, it-will not appear in the output. Similarly, when a cost is implied but-not written, it will not appear in the output. You can use the-‘-x’/‘--explicit’ flag to make all amounts and costs explicit, which can-be useful for troubleshooting or for making your journal more readable-and robust against data entry errors. ‘-x’ is also implied by using any-of ‘-B’,‘-V’,‘-X’,‘--value’.-- Note, ‘-x’/‘--explicit’ will cause postings with a multi-commodity-amount (these can arise when a multi-commodity transaction has an-implicit amount) to be split into multiple single-commodity postings,-keeping the output parseable.-- With ‘-B’/‘--cost’, amounts with costs are converted to cost using-that price. This can be used for troubleshooting.-- With ‘-m DESC’/‘--match=DESC’, print does a fuzzy search for one-recent transaction whose description is most similar to DESC. DESC-should contain at least two characters. If there is no similar-enough-match, no transaction will be shown and the program exit code will be-non-zero.-- With ‘--new’, hledger prints only transactions it has not seen on a-previous run. This uses the same deduplication system as the ‘import’-command. (See import’s docs for details.)-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, and-(experimental) ‘json’ and ‘sql’.-- Here’s an example of print’s CSV output:--$ hledger print -Ocsv-"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"-"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""-"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""-"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""-"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""-"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""-"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""-"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""-"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""-"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""-"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""-"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""-- • There is one CSV record per posting, with the parent transaction’s- fields repeated.- • The "txnidx" (transaction index) field shows which postings belong- to the same transaction. (This number might change if transactions- are reordered within the file, files are parsed/included in a- different order, etc.)- • The amount is separated into "commodity" (the symbol) and "amount"- (numeric quantity) fields.- • The numeric amount is repeated in either the "credit" or "debit"- column, for convenience. (Those names are not accurate in the- accounting sense; it just puts negative amounts under credit and- zero or greater amounts under debit.)---File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS--24.24 register-==============--(reg)-- Show postings and their running total.-- The register command displays matched postings, across all accounts,-in date order, with their running total or running historical balance.-(See also the ‘aregister’ command, which shows matched transactions in a-specific account.)-- register normally shows line per posting, but note that-multi-commodity amounts will occupy multiple lines (one line per-commodity).-- It is typically used with a query selecting a particular account, to-see that account’s activity:--$ hledger register checking-2008/01/01 income assets:bank:checking $1 $1-2008/06/01 gift assets:bank:checking $1 $2-2008/06/02 save assets:bank:checking $-1 $1-2008/12/31 pay off assets:bank:checking $-1 0-- With ‘--date2’, it shows and sorts by secondary date instead.-- For performance reasons, column widths are chosen based on the first-1000 lines; this means unusually wide values in later lines can cause-visual discontinuities as column widths are adjusted. If you want to-ensure perfect alignment, at the cost of more time and memory, use the-‘--align-all’ flag.-- The ‘--historical’/‘-H’ flag adds the balance from any undisplayed-prior postings to the running total. This is useful when you want to-see only recent activity, with a historically accurate running balance:--$ hledger register checking -b 2008/6 --historical-2008/06/01 gift assets:bank:checking $1 $2-2008/06/02 save assets:bank:checking $-1 $1-2008/12/31 pay off assets:bank:checking $-1 0-- The ‘--depth’ option limits the amount of sub-account detail-displayed.-- The ‘--average’/‘-A’ flag shows the running average posting amount-instead of the running total (so, the final number displayed is the-average for the whole report period). This flag implies ‘--empty’ (see-below). It is affected by ‘--historical’. It works best when showing-just one account and one commodity.-- The ‘--related’/‘-r’ flag shows the _other_ postings in the-transactions of the postings which would normally be shown.-- The ‘--invert’ flag negates all amounts. For example, it can be used-on an income account where amounts are normally displayed as negative-numbers. It’s also useful to show postings on the checking account-together with the related account:--$ hledger register --related --invert assets:checking-- With a reporting interval, register shows summary postings, one per-interval, aggregating the postings to each account:--$ hledger register --monthly income-2008/01 income:salary $-1 $-1-2008/06 income:gifts $-1 $-2-- Periods with no activity, and summary postings with a zero amount,-are not shown by default; use the ‘--empty’/‘-E’ flag to see them:--$ hledger register --monthly income -E-2008/01 income:salary $-1 $-1-2008/02 0 $-1-2008/03 0 $-1-2008/04 0 $-1-2008/05 0 $-1-2008/06 income:gifts $-1 $-2-2008/07 0 $-2-2008/08 0 $-2-2008/09 0 $-2-2008/10 0 $-2-2008/11 0 $-2-2008/12 0 $-2-- Often, you’ll want to see just one line per interval. The ‘--depth’-option helps with this, causing subaccounts to be aggregated:--$ hledger register --monthly assets --depth 1h-2008/01 assets $1 $1-2008/06 assets $-1 0-2008/12 assets $-1 $-1-- Note when using report intervals, if you specify start/end dates-these will be adjusted outward if necessary to contain a whole number of-intervals. This ensures that the first and last intervals are full-length and comparable to the others in the report.-- With ‘-m DESC’/‘--match=DESC’, register does a fuzzy search for one-recent posting whose description is most similar to DESC. DESC should-contain at least two characters. If there is no similar-enough match,-no posting will be shown and the program exit code will be non-zero.--* Menu:--* Custom register output::---File: hledger.info, Node: Custom register output, Up: register--24.24.1 Custom register output---------------------------------register uses the full terminal width by default, except on windows.-You can override this by setting the ‘COLUMNS’ environment variable (not-a bash shell variable) or by using the ‘--width’/‘-w’ option.-- The description and account columns normally share the space equally-(about half of (width - 40) each). You can adjust this by adding a-description width as part of –width’s argument, comma-separated:-‘--width W,D’ . Here’s a diagram (won’t display correctly in –help):--<--------------------------------- width (W) ---------------------------------->-date (10) description (D) account (W-41-D) amount (12) balance (12)-DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA-- and some examples:--$ hledger reg # use terminal width (or 80 on windows)-$ hledger reg -w 100 # use width 100-$ COLUMNS=100 hledger reg # set with one-time environment variable-$ export COLUMNS=100; hledger reg # set till session end (or window resize)-$ hledger reg -w 100,40 # set overall width 100, description width 40-$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, and-(experimental) ‘json’.---File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS--24.25 rewrite-=============--Print all transactions, rewriting the postings of matched transactions.-For now the only rewrite available is adding new postings, like print-–auto.-- This is a start at a generic rewriter of transaction entries. It-reads the default journal and prints the transactions, like print, but-adds one or more specified postings to any transactions matching QUERY.-The posting amounts can be fixed, or a multiplier of the existing-transaction’s first posting amount.-- Examples:--$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'-$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'-$ hledger-rewrite.hs -f rewrites.hledger-- rewrites.hledger may consist of entries like:--= ^income amt:<0 date:2017- (liabilities:tax) *0.33 ; tax on income- (reserve:grocery) *0.25 ; reserve 25% for grocery- (reserve:) *0.25 ; reserve 25% for grocery-- Note the single quotes to protect the dollar sign from bash, and the-two spaces between account and amount.-- More:--$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...-$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'-$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'-$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'-- Argument for ‘--add-posting’ option is a usual posting of transaction-with an exception for amount specification. More precisely, you can use-‘'*'’ (star symbol) before the amount to indicate that that this is a-factor for an amount of original matched posting. If the amount-includes a commodity name, the new posting amount will be in the new-commodity; otherwise, it will be in the matched posting amount’s-commodity.--* Menu:--* Re-write rules in a file::-* Diff output format::-* rewrite vs print --auto::---File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite--24.25.1 Re-write rules in a file-----------------------------------During the run this tool will execute so called "Automated Transactions"-found in any journal it process. I.e instead of specifying this-operations in command line you can put them in a journal file.--$ rewrite-rules.journal-- Make contents look like this:--= ^income- (liabilities:tax) *.33--= expenses:gifts- budget:gifts *-1- assets:budget *1-- Note that ‘'='’ (equality symbol) that is used instead of date in-transactions you usually write. It indicates the query by which you-want to match the posting to add new ones.--$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal-- This is something similar to the commands pipeline:--$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \- | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \- --add-posting 'assets:budget *1' \- > rewritten-tidy-output.journal-- It is important to understand that relative order of such entries in-journal is important. You can re-use result of previously added-postings.---File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite--24.25.2 Diff output format-----------------------------To use this tool for batch modification of your journal files you may-find useful output in form of unified diff.--$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'-- Output might look like:----- /tmp/examples/sample.journal-+++ /tmp/examples/sample.journal-@@ -18,3 +18,4 @@- 2008/01/01 income-- assets:bank:checking $1-+ assets:bank:checking $1- income:salary-+ (liabilities:tax) 0-@@ -22,3 +23,4 @@- 2008/06/01 gift-- assets:bank:checking $1-+ assets:bank:checking $1- income:gifts-+ (liabilities:tax) 0-- If you’ll pass this through ‘patch’ tool you’ll get transactions-containing the posting that matches your query be updated. Note that-multiple files might be update according to list of input files-specified via ‘--file’ options and ‘include’ directives inside of these-files.-- Be careful. Whole transaction being re-formatted in a style of-output from ‘hledger print’.-- See also:-- https://github.com/simonmichael/hledger/issues/99---File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite--24.25.3 rewrite vs. print –auto----------------------------------This command predates print –auto, and currently does much the same-thing, but with these differences:-- • with multiple files, rewrite lets rules in any file affect all- other files. print –auto uses standard directive scoping; rules- affect only child files.-- • rewrite’s query limits which transactions can be rewritten; all are- printed. print –auto’s query limits which transactions are- printed.-- • rewrite applies rules specified on command line or in the journal.- print –auto applies rules specified in the journal.---File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: PART 4 COMMANDS--24.26 roi-=========--Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on-your investments.-- At a minimum, you need to supply a query (which could be just an-account name) to select your investment(s) with ‘--inv’, and another-query to identify your profit and loss transactions with ‘--pnl’.-- If you do not record changes in the value of your investment-manually, or do not require computation of time-weighted return (TWR),-‘--pnl’ could be an empty query (‘--pnl ""’ or ‘--pnl STR’ where ‘STR’-does not match any of your accounts).-- This command will compute and display the internalized rate of return-(IRR) and time-weighted rate of return (TWR) for your investments for-the time period requested. Both rates of return are annualized before-display, regardless of the length of reporting interval.-- Price directives will be taken into account if you supply appropriate-‘--cost’ or ‘--value’ flags (see VALUATION).-- Note, in some cases this report can fail, for these reasons:-- • Error (NotBracketed): No solution for Internal Rate of Return- (IRR). Possible causes: IRR is huge (>1000000%), balance of- investment becomes negative at some point in time.- • Error (SearchFailed): Failed to find solution for Internal Rate of- Return (IRR). Either search does not converge to a solution, or- converges too slowly.-- Examples:-- • Using roi to compute total return of investment in stocks:- https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger-- • Cookbook > Return on Investment: https://hledger.org/roi.html--* Menu:--* Spaces and special characters in --inv and --pnl::-* Semantics of --inv and --pnl::-* IRR and TWR explained::---File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi--24.26.1 Spaces and special characters in ‘--inv’ and-------------------------------------------------------‘--pnl’ Note that ‘--inv’ and ‘--pnl’’s argument is a query, and queries-could have several space-separated terms (see QUERIES).-- To indicate that all search terms form single command-line argument,-you will need to put them in quotes (see Special characters):--$ hledger roi --inv 'term1 term2 term3 ...'-- If any query terms contain spaces themselves, you will need an extra-level of nested quoting, eg:--$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"---File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi--24.26.2 Semantics of ‘--inv’ and ‘--pnl’-------------------------------------------Query supplied to ‘--inv’ has to match all transactions that are related-to your investment. Transactions not matching ‘--inv’ will be ignored.-- In these transactions, ROI will conside postings that match ‘--inv’-to be "investment postings" and other postings (not matching ‘--inv’)-will be sorted into two categories: "cash flow" and "profit and loss",-as ROI needs to know which part of the investment value is your-contributions and which is due to the return on investment.-- • "Cash flow" is depositing or withdrawing money, buying or selling- assets, or otherwise converting between your investment commodity- and any other commodity. Example:-- 2019-01-01 Investing in Snake Oil- assets:cash -$100- investment:snake oil- - 2020-01-01 Selling my Snake Oil- assets:cash $10- investment:snake oil = 0-- • "Profit and loss" is change in the value of your investment:-- 2019-06-01 Snake Oil falls in value- investment:snake oil = $57- equity:unrealized profit or loss-- All non-investment postings are assumed to be "cash flow", unless-they match ‘--pnl’ query. Changes in value of your investment due to-"profit and loss" postings will be considered as part of your investment-return.-- Example: if you use ‘--inv snake --pnl equity:unrealized’, then-postings in the example below would be classifed as:--2019-01-01 Snake Oil #1- assets:cash -$100 ; cash flow posting- investment:snake oil ; investment posting--2019-03-01 Snake Oil #2- equity:unrealized pnl -$100 ; profit and loss posting- snake oil ; investment posting--2019-07-01 Snake Oil #3- equity:unrealized pnl ; profit and loss posting- cash -$100 ; cash flow posting- snake oil $50 ; investment posting---File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi--24.26.3 IRR and TWR explained--------------------------------"ROI" stands for "return on investment". Traditionally this was-computed as a difference between current value of investment and its-initial value, expressed in percentage of the initial value.-- However, this approach is only practical in simple cases, where-investments receives no in-flows or out-flows of money, and where rate-of growth is fixed over time. For more complex scenarios you need-different ways to compute rate of return, and this command implements-two of them: IRR and TWR.-- Internal rate of return, or "IRR" (also called "money-weighted rate-of return") takes into account effects of in-flows and out-flows.-Naively, if you are withdrawing from your investment, your future gains-would be smaller (in absolute numbers), and will be a smaller percentage-of your initial investment, and if you are adding to your investment,-you will receive bigger absolute gains (but probably at the same rate of-return). IRR is a way to compute rate of return for each period between-in-flow or out-flow of money, and then combine them in a way that gives-you a compound annual rate of return that investment is expected to-generate.-- As mentioned before, in-flows and out-flows would be any cash that-you personally put in or withdraw, and for the "roi" command, these are-the postings that match the query in the‘--inv’ argument and NOT match-the query in the‘--pnl’ argument.-- If you manually record changes in the value of your investment as-transactions that balance them against "profit and loss" (or "unrealized-gains") account or use price directives, then in order for IRR to-compute the precise effect of your in-flows and out-flows on the rate of-return, you will need to record the value of your investement on or-close to the days when in- or out-flows occur.-- In technical terms, IRR uses the same approach as computation of net-present value, and tries to find a discount rate that makes net present-value of all the cash flows of your investment to add up to zero. This-could be hard to wrap your head around, especially if you haven’t done-discounted cash flow analysis before. Implementation of IRR in hledger-should produce results that match the ‘XIRR’ formula in Excel.-- Second way to compute rate of return that ‘roi’ command implements is-called "time-weighted rate of return" or "TWR". Like IRR, it will also-break the history of your investment into periods between in-flows,-out-flows and value changes, to compute rate of return per each period-and then a compound rate of return. However, internal workings of TWR-are quite different.-- TWR represents your investment as an imaginary "unit fund" where-in-flows/ out-flows lead to buying or selling "units" of your investment-and changes in its value change the value of "investment unit". Change-in "unit price" over the reporting period gives you rate of return of-your investment.-- References:-- • Explanation of rate of return- • Explanation of IRR- • Explanation of TWR- • Examples of computing IRR and TWR and discussion of the limitations- of both metrics---File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS--24.27 stats-===========--Show journal and performance statistics.-- The stats command displays summary information for the whole journal,-or a matched part of it. With a reporting interval, it shows a report-for each report period.-- At the end, it shows (in the terminal) the overall run time and-number of transactions processed per second. Note these are approximate-and will vary based on machine, current load, data size, hledger-version, haskell lib versions, GHC version.. but they may be of-interest. The ‘stats’ command’s run time is similar to that of a-single-column balance report.-- Example:--$ hledger stats -f examples/1000x1000x10.journal-Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal-Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days)-Last transaction : 2002-09-26 (6995 days ago)-Transactions : 1000 (1.0 per day)-Transactions last 30 days: 0 (0.0 per day)-Transactions last 7 days : 0 (0.0 per day)-Payees/descriptions : 1000-Accounts : 1000 (depth 10)-Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)-Market prices : 1000 (A)--Run time : 0.12 s-Throughput : 8342 txns/s-- This command supports the -o/–output-file option (but not--O/–output-format selection).---File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS--24.28 tags-==========--List the tags used in the journal, or their values.-- This command lists the tag names used in the journal, whether on-transactions, postings, or account declarations.-- With a TAGREGEX argument, only tag names matching this regular-expression (case insensitive, infix matched) are shown.-- With QUERY arguments, only transactions and accounts matching this-query are considered. If the query involves transaction fields (date:,-desc:, amt:, ...), the search is restricted to the matched transactions-and their accounts.-- With the –values flag, the tags’ unique non-empty values are listed-instead. With -E/–empty, blank/empty values are also shown.-- With –parsed, tags or values are shown in the order they were parsed,-with duplicates included. (Except, tags from account declarations are-always shown first.)-- Tip: remember, accounts also acquire tags from their parents,-postings also acquire tags from their account and transaction,-transactions also acquire tags from their postings.---File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS--24.29 test-==========--Run built-in unit tests.-- This command runs the unit tests built in to hledger and hledger-lib,-printing the results on stdout. If any test fails, the exit code will-be non-zero.-- This is mainly used by hledger developers, but you can also use it to-sanity-check the installed hledger executable on your platform. All-tests are expected to pass - if you ever see a failure, please report as-a bug!-- This command also accepts tasty test runner options, written after a-– (double hyphen). Eg to run only the tests in Hledger.Data.Amount,-with ANSI colour codes disabled:--$ hledger test -- -pData.Amount --color=never-- For help on these, see https://github.com/feuerbach/tasty#options-(‘-- --help’ currently doesn’t show them).---File: hledger.info, Node: PART 5 COMMON TASKS, Prev: PART 4 COMMANDS, Up: Top--25 PART 5: COMMON TASKS-***********************--Here are some quick examples of how to do some basic tasks with hledger.--* Menu:--* Getting help::-* Constructing command lines::-* Starting a journal file::-* Setting opening balances::-* Recording transactions::-* Reconciling::-* Reporting::-* Migrating to a new file::---File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS--25.1 Getting help-=================--Here’s how to list commands and view options and command docs:--$ hledger # show available commands-$ hledger --help # show common options-$ hledger CMD --help # show CMD's options, common options and CMD's documentation-- You can also view your hledger version’s manual in several formats by-using the help command. Eg:--$ hledger help # show the hledger manual with info, man or $PAGER (best available)-$ hledger help journal # show the journal topic in the hledger manual-$ hledger help --help # find out more about the help command-- To view manuals and introductory docs on the web, visit-https://hledger.org. Chat and mail list support and discussion archives-can be found at https://hledger.org/support.---File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS--25.2 Constructing command lines-===============================--hledger has a flexible command line interface. We strive to keep it-simple and ergonomic, but if you run into one of the sharp edges-described in OPTIONS, here are some tips that might help:-- • command-specific options must go after the command (it’s fine to- put common options there too: ‘hledger CMD OPTS ARGS’)- • running add-on executables directly simplifies command line parsing- (‘hledger-ui OPTS ARGS’)- • enclose "problematic" args in single quotes- • if needed, also add a backslash to hide regular expression- metacharacters from the shell- • to see how a misbehaving command line is being parsed, add- ‘--debug=2’.---File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: PART 5 COMMON TASKS--25.3 Starting a journal file-============================--hledger looks for your accounting data in a journal file,-‘$HOME/.hledger.journal’ by default:--$ hledger stats-The hledger journal file "/Users/simon/.hledger.journal" was not found.-Please create it first, eg with "hledger add" or a text editor.-Or, specify an existing journal file with -f or LEDGER_FILE.-- You can override this by setting the ‘LEDGER_FILE’ environment-variable. It’s a good practice to keep this important file under-version control, and to start a new file each year. So you could do-something like this:--$ mkdir ~/finance-$ cd ~/finance-$ git init-Initialized empty Git repository in /Users/simon/finance/.git/-$ touch 2020.journal-$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc-$ source ~/.bashrc-$ hledger stats-Main file : /Users/simon/finance/2020.journal-Included files : -Transactions span : to (0 days)-Last transaction : none-Transactions : 0 (0.0 per day)-Transactions last 30 days: 0 (0.0 per day)-Transactions last 7 days : 0 (0.0 per day)-Payees/descriptions : 0-Accounts : 0 (depth 0)-Commodities : 0 ()-Market prices : 0 ()---File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: PART 5 COMMON TASKS--25.4 Setting opening balances-=============================--Pick a starting date for which you can look up the balances of some-real-world assets (bank accounts, wallet..) and liabilities (credit-cards..).-- To avoid a lot of data entry, you may want to start with just one or-two accounts, like your checking account or cash wallet; and pick a-recent starting date, like today or the start of the week. You can-always come back later and add more accounts and older transactions, eg-going back to january 1st.-- Add an opening balances transaction to the journal, declaring the-balances on this date. Here are two ways to do it:-- • The first way: open the journal in any text editor and save an- entry like this:-- 2020-01-01 * opening balances- assets:bank:checking $1000 = $1000- assets:bank:savings $2000 = $2000- assets:cash $100 = $100- liabilities:creditcard $-50 = $-50- equity:opening/closing balances-- These are start-of-day balances, ie whatever was in the account at- the end of the previous day.-- The * after the date is an optional status flag. Here it means- "cleared & confirmed".-- The currency symbols are optional, but usually a good idea as- you’ll be dealing with multiple currencies sooner or later.-- The = amounts are optional balance assertions, providing extra- error checking.-- • The second way: run ‘hledger add’ and follow the prompts to record- a similar transaction:-- $ hledger add- Adding transactions to journal file /Users/simon/finance/2020.journal- Any command line arguments will be used as defaults.- Use tab key to complete, readline keys to edit, enter to accept defaults.- An optional (CODE) may follow transaction dates.- An optional ; COMMENT may follow descriptions or amounts.- If you make a mistake, enter < at any prompt to go one step backward.- To end a transaction, enter . when prompted.- To quit, enter . at a date prompt or press control-d or control-c.- Date [2020-02-07]: 2020-01-01- Description: * opening balances- Account 1: assets:bank:checking- Amount 1: $1000- Account 2: assets:bank:savings- Amount 2 [$-1000]: $2000- Account 3: assets:cash- Amount 3 [$-3000]: $100- Account 4: liabilities:creditcard- Amount 4 [$-3100]: $-50- Account 5: equity:opening/closing balances- Amount 5 [$-3050]: - Account 6 (or . or enter to finish this transaction): .- 2020-01-01 * opening balances- assets:bank:checking $1000- assets:bank:savings $2000- assets:cash $100- liabilities:creditcard $-50- equity:opening/closing balances $-3050- - Save this transaction to the journal ? [y]: - Saved.- Starting the next transaction (. or ctrl-D/ctrl-C to quit)- Date [2020-01-01]: .-- If you’re using version control, this could be a good time to commit-the journal. Eg:--$ git commit -m 'initial balances' 2020.journal---File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS--25.5 Recording transactions-===========================--As you spend or receive money, you can record these transactions using-one of the methods above (text editor, hledger add) or by using the-hledger-iadd or hledger-web add-ons, or by using the import command to-convert CSV data downloaded from your bank.-- Here are some simple transactions, see the hledger_journal(5) manual-and hledger.org for more ideas:--2020/1/10 * gift received- assets:cash $20- income:gifts--2020.1.12 * farmers market- expenses:food $13- assets:cash--2020-01-15 paycheck- income:salary- assets:bank:checking $1000---File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS--25.6 Reconciling-================--Periodically you should reconcile - compare your hledger-reported-balances against external sources of truth, like bank statements or your-bank’s website - to be sure that your ledger accurately represents the-real-world balances (and, that the real-world institutions have not made-a mistake!). This gets easy and fast with (1) practice and (2)-frequency. If you do it daily, it can take 2-10 minutes. If you let it-pile up, expect it to take longer as you hunt down errors and-discrepancies.-- A typical workflow:-- 1. Reconcile cash. Count what’s in your wallet. Compare with what- hledger reports (‘hledger bal cash’). If they are different, try- to remember the missing transaction, or look for the error in the- already-recorded transactions. A register report can be helpful- (‘hledger reg cash’). If you can’t find the error, add an- adjustment transaction. Eg if you have $105 after the above, and- can’t explain the missing $2, it could be:-- 2020-01-16 * adjust cash- assets:cash $-2 = $105- expenses:misc-- 2. Reconcile checking. Log in to your bank’s website. Compare- today’s (cleared) balance with hledger’s cleared balance (‘hledger- bal checking -C’). If they are different, track down the error or- record the missing transaction(s) or add an adjustment transaction,- similar to the above. Unlike the cash case, you can usually- compare the transaction history and running balance from your bank- with the one reported by ‘hledger reg checking -C’. This will be- easier if you generally record transaction dates quite similar to- your bank’s clearing dates.-- 3. Repeat for other asset/liability accounts.-- Tip: instead of the register command, use hledger-ui to see a-live-updating register while you edit the journal: ‘hledger-ui --watch---register checking -C’-- After reconciling, it could be a good time to mark the reconciled-transactions’ status as "cleared and confirmed", if you want to track-that, by adding the ‘*’ marker. Eg in the paycheck transaction above,-insert ‘*’ between ‘2020-01-15’ and ‘paycheck’-- If you’re using version control, this can be another good time to-commit:--$ git commit -m 'txns' 2020.journal---File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS--25.7 Reporting-==============--Here are some basic reports.-- Show all transactions:--$ hledger print-2020-01-01 * opening balances- assets:bank:checking $1000- assets:bank:savings $2000- assets:cash $100- liabilities:creditcard $-50- equity:opening/closing balances $-3050--2020-01-10 * gift received- assets:cash $20- income:gifts--2020-01-12 * farmers market- expenses:food $13- assets:cash--2020-01-15 * paycheck- income:salary- assets:bank:checking $1000--2020-01-16 * adjust cash- assets:cash $-2 = $105- expenses:misc-- Show account names, and their hierarchy:--$ hledger accounts --tree-assets- bank- checking- savings- cash-equity- opening/closing balances-expenses- food- misc-income- gifts- salary-liabilities- creditcard-- Show all account totals:--$ hledger balance- $4105 assets- $4000 bank- $2000 checking- $2000 savings- $105 cash- $-3050 equity:opening/closing balances- $15 expenses- $13 food- $2 misc- $-1020 income- $-20 gifts- $-1000 salary- $-50 liabilities:creditcard---------------------- 0-- Show only asset and liability balances, as a flat list, limited to-depth 2:--$ hledger bal assets liabilities -2- $4000 assets:bank- $105 assets:cash- $-50 liabilities:creditcard---------------------- $4055-- Show the same thing without negative numbers, formatted as a simple-balance sheet:--$ hledger bs -2-Balance Sheet 2020-01-16-- || 2020-01-16 -========================++============- Assets || -------------------------++------------- assets:bank || $4000 - assets:cash || $105 -------------------------++------------- || $4105 -========================++============- Liabilities || -------------------------++------------- liabilities:creditcard || $50 -------------------------++------------- || $50 -========================++============- Net: || $4055 -- The final total is your "net worth" on the end date. (Or use ‘bse’-for a full balance sheet with equity.)-- Show income and expense totals, formatted as an income statement:--hledger is -Income Statement 2020-01-01-2020-01-16-- || 2020-01-01-2020-01-16 -===============++=======================- Revenues || ----------------++------------------------ income:gifts || $20 - income:salary || $1000 ----------------++------------------------ || $1020 -===============++=======================- Expenses || ----------------++------------------------ expenses:food || $13 - expenses:misc || $2 ----------------++------------------------ || $15 -===============++=======================- Net: || $1005 -- The final total is your net income during this period.-- Show transactions affecting your wallet, with running total:--$ hledger register cash-2020-01-01 opening balances assets:cash $100 $100-2020-01-10 gift received assets:cash $20 $120-2020-01-12 farmers market assets:cash $-13 $107-2020-01-16 adjust cash assets:cash $-2 $105-- Show weekly posting counts as a bar chart:--$ hledger activity -W-2019-12-30 *****-2020-01-06 ****-2020-01-13 ****---File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS--25.8 Migrating to a new file-============================--At the end of the year, you may want to continue your journal in a new-file, so that old transactions don’t slow down or clutter your reports,-and to help ensure the integrity of your accounting history. See the-close command.-- If using version control, don’t forget to ‘git add’ the new file.---Tag Table:-Node: Top210-Node: PART 1 USER INTERFACE3944-Ref: #part-1-user-interface4085-Node: Options4085-Ref: #options4204-Node: General options4346-Ref: #general-options4471-Node: Command options8921-Ref: #command-options9072-Node: Command arguments9488-Ref: #command-arguments9646-Node: Special characters10548-Ref: #special-characters10711-Node: Single escaping shell metacharacters10874-Ref: #single-escaping-shell-metacharacters11115-Node: Double escaping regular expression metacharacters11750-Ref: #double-escaping-regular-expression-metacharacters12061-Node: Triple escaping for add-on commands12631-Ref: #triple-escaping-for-add-on-commands12891-Node: Less escaping13559-Ref: #less-escaping13713-Node: Unicode characters14051-Ref: #unicode-characters14216-Node: Regular expressions15648-Ref: #regular-expressions15788-Node: Environment17642-Ref: #environment17753-Node: Input19364-Ref: #input19464-Node: Data formats20027-Ref: #data-formats20140-Node: Multiple files21592-Ref: #multiple-files21729-Node: Strict mode22214-Ref: #strict-mode22324-Node: Commands23078-Ref: #commands23179-Node: Add-on commands23663-Ref: #add-on-commands23765-Node: Output24932-Ref: #output25035-Node: Output destination25151-Ref: #output-destination25282-Node: Output format25711-Ref: #output-format25857-Node: CSV output27429-Ref: #csv-output27545-Node: HTML output27650-Ref: #html-output27788-Node: JSON output27888-Ref: #json-output28026-Node: SQL output28958-Ref: #sql-output29074-Node: Commodity styles29597-Ref: #commodity-styles29737-Node: Colour30344-Ref: #colour30462-Node: Box-drawing30896-Ref: #box-drawing31020-Node: Debug output31334-Ref: #debug-output31445-Node: Limitations32120-Ref: #limitations32240-Node: Troubleshooting33015-Ref: #troubleshooting33156-Node: PART 2 DATA FORMATS35678-Ref: #part-2-data-formats35825-Node: Journal35825-Ref: #journal35936-Node: Journal cheatsheet36579-Ref: #journal-cheatsheet36720-Node: About journal format40708-Ref: #about-journal-format40870-Node: Comments42408-Ref: #comments42540-Node: Transactions43394-Ref: #transactions43519-Node: Dates44553-Ref: #dates44662-Node: Simple dates44707-Ref: #simple-dates44825-Node: Posting dates45357-Ref: #posting-dates45477-Node: Status46460-Ref: #status46563-Node: Code48315-Ref: #code48420-Node: Description48652-Ref: #description48785-Node: Payee and note49107-Ref: #payee-and-note49215-Node: Transaction comments49562-Ref: #transaction-comments49717-Node: Postings50088-Ref: #postings50223-Node: Account names51232-Ref: #account-names51364-Node: Amounts53066-Ref: #amounts53183-Node: Decimal marks digit group marks54172-Ref: #decimal-marks-digit-group-marks54349-Node: Commodity55373-Ref: #commodity55562-Node: Directives influencing number parsing and display56544-Ref: #directives-influencing-number-parsing-and-display56805-Node: Commodity display style57267-Ref: #commodity-display-style57475-Node: Rounding59686-Ref: #rounding59806-Node: Costs60107-Ref: #costs60225-Node: Other cost/lot notations62256-Ref: #other-costlot-notations62390-Node: Balance assertions65143-Ref: #balance-assertions65296-Node: Assertions and ordering66389-Ref: #assertions-and-ordering66580-Node: Assertions and multiple included files67282-Ref: #assertions-and-multiple-included-files67544-Node: Assertions and multiple -f files68052-Ref: #assertions-and-multiple--f-files68305-Node: Assertions and commodities68714-Ref: #assertions-and-commodities68938-Node: Assertions and prices70128-Ref: #assertions-and-prices70336-Node: Assertions and subaccounts70767-Ref: #assertions-and-subaccounts70990-Node: Assertions and virtual postings71332-Ref: #assertions-and-virtual-postings71572-Node: Assertions and auto postings71712-Ref: #assertions-and-auto-postings71944-Node: Assertions and precision72615-Ref: #assertions-and-precision72799-Node: Posting comments73066-Ref: #posting-comments73214-Node: Tags73599-Ref: #tags73715-Node: Tag values74920-Ref: #tag-values75011-Node: Directives75784-Ref: #directives75913-Node: Directive effects77781-Ref: #directive-effects77937-Node: Directives and multiple files81020-Ref: #directives-and-multiple-files81200-Node: account directive81910-Ref: #account-directive82072-Node: Account comments83492-Ref: #account-comments83644-Node: Account subdirectives84164-Ref: #account-subdirectives84357-Node: Account error checking84499-Ref: #account-error-checking84699-Node: Account display order85918-Ref: #account-display-order86108-Node: Account types87247-Ref: #account-types87390-Node: alias directive91125-Ref: #alias-directive91292-Node: Basic aliases92352-Ref: #basic-aliases92485-Node: Regex aliases93239-Ref: #regex-aliases93398-Node: Combining aliases94292-Ref: #combining-aliases94472-Node: Aliases and multiple files95766-Ref: #aliases-and-multiple-files95972-Node: end aliases directive96557-Ref: #end-aliases-directive96782-Node: Aliases can generate bad account names96931-Ref: #aliases-can-generate-bad-account-names97181-Node: Aliases and account types97778-Ref: #aliases-and-account-types97972-Node: commodity directive98674-Ref: #commodity-directive98854-Node: Commodity error checking101458-Ref: #commodity-error-checking101606-Node: decimal-mark directive102135-Ref: #decimal-mark-directive102323-Node: include directive102724-Ref: #include-directive102894-Node: P directive103842-Ref: #p-directive103993-Node: payee directive104892-Ref: #payee-directive105047-Node: tag directive105367-Ref: #tag-directive105528-Node: Periodic transactions106000-Ref: #periodic-transactions106166-Node: Periodic rule syntax107904-Ref: #periodic-rule-syntax108084-Node: Periodic rules and relative dates108739-Ref: #periodic-rules-and-relative-dates109007-Node: Two spaces between period expression and description!109546-Ref: #two-spaces-between-period-expression-and-description109825-Node: Other syntax110515-Ref: #other-syntax110641-Node: Auto postings111286-Ref: #auto-postings111422-Node: Auto postings and multiple files113933-Ref: #auto-postings-and-multiple-files114135-Node: Auto postings and dates114352-Ref: #auto-postings-and-dates114624-Node: Auto postings and transaction balancing / inferred amounts / balance assertions114799-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions115138-Node: Auto posting tags115645-Ref: #auto-posting-tags115858-Node: Balance assignments116520-Ref: #balance-assignments116700-Node: Balance assignments and prices118034-Ref: #balance-assignments-and-prices118204-Node: Bracketed posting dates118415-Ref: #bracketed-posting-dates118601-Node: D directive119145-Ref: #d-directive119319-Node: apply account directive120987-Ref: #apply-account-directive121173-Node: Y directive121872-Ref: #y-directive122038-Node: Secondary dates122882-Ref: #secondary-dates123038-Node: Star comments123870-Ref: #star-comments124032-Node: Valuation expressions124572-Ref: #valuation-expressions124751-Node: Virtual postings124873-Ref: #virtual-postings125054-Node: Other Ledger directives126626-Ref: #other-ledger-directives126791-Node: CSV127361-Ref: #csv127454-Node: CSV rules cheatsheet129557-Ref: #csv-rules-cheatsheet129689-Node: separator131457-Ref: #separator131588-Node: skip132166-Ref: #skip132278-Node: date-format132861-Ref: #date-format132986-Node: timezone133732-Ref: #timezone133859-Node: newest-first134892-Ref: #newest-first135034-Node: intra-day-reversed135618-Ref: #intra-day-reversed135776-Node: decimal-mark136273-Ref: #decimal-mark136418-Node: fields list136757-Ref: #fields-list136898-Node: Field assignment138621-Ref: #field-assignment138765-Node: Field names139814-Ref: #field-names139945-Node: date field141166-Ref: #date-field141284-Node: date2 field141336-Ref: #date2-field141477-Node: status field141539-Ref: #status-field141682-Node: code field141737-Ref: #code-field141882-Node: description field141933-Ref: #description-field142093-Node: comment field142158-Ref: #comment-field142313-Node: account field142626-Ref: #account-field142776-Node: amount field143372-Ref: #amount-field143521-Node: currency field145626-Ref: #currency-field145779-Node: balance field146048-Ref: #balance-field146180-Node: if block146568-Ref: #if-block146693-Node: Matchers148117-Ref: #matchers148231-Node: if table149761-Ref: #if-table149887-Node: balance-type151323-Ref: #balance-type151456-Node: include152164-Ref: #include152295-Node: Working with CSV152745-Ref: #working-with-csv152892-Node: Rapid feedback153263-Ref: #rapid-feedback153396-Node: Valid CSV153852-Ref: #valid-csv153998-Node: File Extension154752-Ref: #file-extension154925-Node: Reading CSV from standard input155515-Ref: #reading-csv-from-standard-input155739-Node: Reading multiple CSV files155905-Ref: #reading-multiple-csv-files156123-Node: Valid transactions156372-Ref: #valid-transactions156566-Node: Deduplicating importing157194-Ref: #deduplicating-importing157389-Node: Setting amounts158435-Ref: #setting-amounts158606-Node: Amount signs161129-Ref: #amount-signs161297-Node: Setting currency/commodity162036-Ref: #setting-currencycommodity162240-Node: Amount decimal places163432-Ref: #amount-decimal-places163638-Node: Referencing other fields163956-Ref: #referencing-other-fields164169-Node: How CSV rules are evaluated165072-Ref: #how-csv-rules-are-evaluated165289-Node: Well factored rules166802-Ref: #well-factored-rules166970-Node: CSV rules examples167308-Ref: #csv-rules-examples167443-Node: Bank of Ireland167508-Ref: #bank-of-ireland167645-Node: Coinbase169113-Ref: #coinbase169251-Node: Amazon170304-Ref: #amazon170429-Node: Paypal172154-Ref: #paypal172262-Node: Timeclock179908-Ref: #timeclock180013-Node: Timedot182181-Ref: #timedot182304-Node: PART 3 REPORTING CONCEPTS187155-Ref: #part-3-reporting-concepts187319-Node: Time periods187319-Ref: #time-periods187453-Node: Report start & end date187571-Ref: #report-start-end-date187723-Node: Smart dates189456-Ref: #smart-dates189609-Node: Report intervals191569-Ref: #report-intervals191724-Node: Date adjustment192176-Ref: #date-adjustment192336-Node: Period expressions193668-Ref: #period-expressions193809-Node: Period expressions with a report interval195645-Ref: #period-expressions-with-a-report-interval195879-Node: More complex report intervals196109-Ref: #more-complex-report-intervals196354-Node: Multiple weekday intervals198283-Ref: #multiple-weekday-intervals198472-Node: Depth199336-Ref: #depth199438-Node: Queries199758-Ref: #queries199860-Node: Query types200805-Ref: #query-types200926-Node: Combining query terms204266-Ref: #combining-query-terms204443-Node: Queries and command options205541-Ref: #queries-and-command-options205740-Node: Queries and valuation206005-Ref: #queries-and-valuation206200-Node: Querying with account aliases206439-Ref: #querying-with-account-aliases206650-Node: Querying with cost or value206792-Ref: #querying-with-cost-or-value206969-Node: Pivoting207278-Ref: #pivoting207392-Node: Generating data208880-Ref: #generating-data209012-Node: Forecasting209510-Ref: #forecasting209635-Node: Budgeting212522-Ref: #budgeting212642-Node: Cost reporting212913-Ref: #cost-reporting213041-Node: -B Convert to cost214156-Ref: #b-convert-to-cost214312-Node: Equity conversion postings215720-Ref: #equity-conversion-postings215934-Node: Inferring equity postings from cost216829-Ref: #inferring-equity-postings-from-cost217078-Node: Inferring cost from equity postings217897-Ref: #inferring-cost-from-equity-postings218145-Node: When to infer cost/equity219954-Ref: #when-to-infer-costequity220172-Node: How to record conversions220580-Ref: #how-to-record-conversions220772-Node: Conversion with implicit cost221063-Ref: #conversion-with-implicit-cost221268-Node: Conversion with explicit cost222173-Ref: #conversion-with-explicit-cost222418-Node: Conversion with equity postings222845-Ref: #conversion-with-equity-postings223114-Node: Conversion with equity postings and explicit cost223951-Ref: #conversion-with-equity-postings-and-explicit-cost224218-Node: Cost tips224692-Ref: #cost-tips224818-Node: Valuation225554-Ref: #valuation225678-Node: -V Value226464-Ref: #v-value226590-Node: -X Value in specified commodity226789-Ref: #x-value-in-specified-commodity226984-Node: Valuation date227141-Ref: #valuation-date227312-Node: Finding market price227751-Ref: #finding-market-price227956-Node: --infer-market-prices market prices from transactions229136-Ref: #infer-market-prices-market-prices-from-transactions229414-Node: Valuation commodity232260-Ref: #valuation-commodity232473-Node: Simple valuation examples233718-Ref: #simple-valuation-examples233916-Node: --value Flexible valuation234579-Ref: #value-flexible-valuation234785-Node: More valuation examples236471-Ref: #more-valuation-examples236680-Node: Interaction of valuation and queries238691-Ref: #interaction-of-valuation-and-queries238932-Node: Effect of valuation on reports239412-Ref: #effect-of-valuation-on-reports239609-Node: PART 4 COMMANDS247368-Ref: #part-4-commands247511-Node: Commands overview247881-Ref: #commands-overview248015-Node: DATA ENTRY248194-Ref: #data-entry248318-Node: DATA CREATION248521-Ref: #data-creation248675-Node: DATA MANAGEMENT248799-Ref: #data-management248964-Node: REPORTS FINANCIAL249089-Ref: #reports-financial249264-Node: REPORTS VERSATILE249579-Ref: #reports-versatile249752-Node: REPORTS BASIC250013-Ref: #reports-basic250165-Node: HELP250698-Ref: #help250820-Node: ADD-ONS250879-Ref: #add-ons250985-Node: accounts251582-Ref: #accounts251715-Node: activity253690-Ref: #activity253809-Node: add254183-Ref: #add254293-Node: aregister257154-Ref: #aregister257275-Node: aregister and custom posting dates260251-Ref: #aregister-and-custom-posting-dates260417-Node: balance260985-Ref: #balance261111-Node: balance features262116-Ref: #balance-features262256-Node: Simple balance report264386-Ref: #simple-balance-report264571-Node: Balance report line format266216-Ref: #balance-report-line-format266418-Node: Filtered balance report268668-Ref: #filtered-balance-report268860-Node: List or tree mode269187-Ref: #list-or-tree-mode269355-Node: Depth limiting270730-Ref: #depth-limiting270896-Node: Dropping top-level accounts271513-Ref: #dropping-top-level-accounts271713-Node: Showing declared accounts272027-Ref: #showing-declared-accounts272226-Node: Sorting by amount272767-Ref: #sorting-by-amount272934-Node: Percentages273624-Ref: #percentages273783-Node: Multi-period balance report274353-Ref: #multi-period-balance-report274553-Node: Balance change end balance276946-Ref: #balance-change-end-balance277155-Node: Balance report types278603-Ref: #balance-report-types278784-Node: Calculation type279300-Ref: #calculation-type279455-Node: Accumulation type279986-Ref: #accumulation-type280166-Node: Valuation type281094-Ref: #valuation-type281282-Node: Combining balance report types282349-Ref: #combining-balance-report-types282543-Node: Budget report284447-Ref: #budget-report284599-Node: Budget report start date290333-Ref: #budget-report-start-date290511-Node: Budgets and subaccounts291873-Ref: #budgets-and-subaccounts292080-Node: Selecting budget goals295566-Ref: #selecting-budget-goals295765-Node: Budget vs forecast296812-Ref: #budget-vs-forecast296971-Node: Data layout298671-Ref: #data-layout298821-Node: Useful balance reports306762-Ref: #useful-balance-reports306912-Node: balancesheet308065-Ref: #balancesheet308210-Node: balancesheetequity309576-Ref: #balancesheetequity309734-Node: cashflow311177-Ref: #cashflow311308-Node: check312794-Ref: #check312908-Node: Basic checks313714-Ref: #basic-checks313834-Node: Strict checks314372-Ref: #strict-checks314515-Node: Other checks314956-Ref: #other-checks315098-Node: Custom checks315675-Ref: #custom-checks315832-Node: More about specific checks316253-Ref: #more-about-specific-checks316415-Node: close317147-Ref: #close317258-Node: close and costs319896-Ref: #close-and-costs320040-Node: close and balance assertions320329-Ref: #close-and-balance-assertions320531-Node: Example retain earnings321702-Ref: #example-retain-earnings321919-Node: Example migrate balances to a new file322277-Ref: #example-migrate-balances-to-a-new-file322542-Node: Example excluding closing/opening transactions323095-Ref: #example-excluding-closingopening-transactions323344-Node: codes324522-Ref: #codes324639-Node: commodities325515-Ref: #commodities325651-Node: descriptions325721-Ref: #descriptions325858-Node: diff326149-Ref: #diff326264-Node: files327310-Ref: #files327419-Node: help327560-Ref: #help-1327669-Node: import328659-Ref: #import328782-Node: Deduplication329890-Ref: #deduplication330015-Node: Import testing331937-Ref: #import-testing332102-Node: Importing balance assignments332953-Ref: #importing-balance-assignments333159-Node: Commodity display styles333816-Ref: #commodity-display-styles333989-Node: incomestatement334118-Ref: #incomestatement334260-Node: notes335627-Ref: #notes335749-Node: payees336111-Ref: #payees336226-Node: prices336751-Ref: #prices336866-Node: print337168-Ref: #print337283-Node: register342729-Ref: #register342851-Node: Custom register output347960-Ref: #custom-register-output348091-Node: rewrite349466-Ref: #rewrite349584-Node: Re-write rules in a file351496-Ref: #re-write-rules-in-a-file351659-Node: Diff output format352812-Ref: #diff-output-format352995-Node: rewrite vs print --auto354107-Ref: #rewrite-vs.-print---auto354269-Node: roi354843-Ref: #roi354950-Node: Spaces and special characters in --inv and --pnl356711-Ref: #spaces-and-special-characters-in---inv-and---pnl356959-Node: Semantics of --inv and --pnl357457-Ref: #semantics-of---inv-and---pnl357704-Node: IRR and TWR explained359582-Ref: #irr-and-twr-explained359742-Node: stats362854-Ref: #stats362962-Node: tags364359-Ref: #tags-1364466-Node: test365483-Ref: #test365576-Node: PART 5 COMMON TASKS366326-Ref: #part-5-common-tasks366459-Node: Getting help366733-Ref: #getting-help366874-Node: Constructing command lines367638-Ref: #constructing-command-lines367839-Node: Starting a journal file368520-Ref: #starting-a-journal-file368727-Node: Setting opening balances369925-Ref: #setting-opening-balances370130-Node: Recording transactions373283-Ref: #recording-transactions373472-Node: Reconciling374028-Ref: #reconciling374180-Node: Reporting376493-Ref: #reporting376642-Node: Migrating to a new file380631-Ref: #migrating-to-a-new-file380788+ This manual is for hledger’s command line interface, version 1.29.1.+It also describes the common options, file formats and concepts used by+all hledger programs. It might accidentally teach you some+bookkeeping/accounting as well! You don’t need to know everything in+here to use hledger productively, but when you have a question about+functionality, this doc should answer it. It is detailed, so do skip+ahead or skim when needed. You can read it on hledger.org, or as an+info manual or man page on your system. You can also get it from+hledger itself with+‘hledger --man’, ‘hledger --info’ or ‘hledger help [TOPIC]’.++ The main function of the hledger CLI is to read plain text files+describing financial transactions, crunch the numbers, and print a+useful report on the terminal (or save it as HTML, CSV, JSON or SQL).+Many reports are available, as subcommands. hledger will also detect+other ‘hledger-*’ executables as extra subcommands.++ hledger reads data from one or more files in journal, timeclock,+timedot, or CSV format. The default file is ‘.hledger.journal’ in your+home directory; this can be overridden with one or more ‘-f FILE’+options, or the ‘LEDGER_FILE’ environment variable. hledger CLI can+also read from stdin with ‘-f-’; more on that below.++ Here is a small but valid hledger journal file describing one+transaction:++2015-10-16 bought food+ expenses:food $10+ assets:cash++ Transactions are dated movements of money (etc.) between two or more+_accounts_: bank accounts, your wallet, revenue/expense categories,+people, etc. You can choose any account names you wish, using ‘:’ to+indicate subaccounts. There must be at least two spaces between account+name and amount. Positive amounts are inflow to that account (_debit_),+negatives are outflow from it (_credit_). (Some reports show revenue,+liability and equity account balances as negative numbers as a result;+this is normal.)++ hledger’s add command can help you add transactions, or you can+install other data entry UIs like hledger-web or hledger-iadd. For more+extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM++ vim-ledger, or VS Code + hledger-vscode are some good choices (see+https://hledger.org/editors.html).++ To get started, run ‘hledger add’ and follow the prompts, or save+some entries like the above in ‘$HOME/.hledger.journal’, then try+commands like:+‘hledger print -x’+‘hledger aregister assets’+‘hledger balance’+‘hledger balancesheet’+‘hledger incomestatement’.+Run ‘hledger’ to list the commands. See also the "Starting a journal+file" and "Setting opening balances" sections in PART 5: COMMON TASKS.++* Menu:++* PART 1 USER INTERFACE::+* Options::+* Environment::+* Input::+* Commands::+* Output::+* Limitations::+* Troubleshooting::+* PART 2 DATA FORMATS::+* Journal::+* CSV::+* Timeclock::+* Timedot::+* PART 3 REPORTING CONCEPTS::+* Time periods::+* Depth::+* Queries::+* Pivoting::+* Generating data::+* Forecasting::+* Budgeting::+* Cost reporting::+* Valuation::+* PART 4 COMMANDS::+* PART 5 COMMON TASKS::+++File: hledger.info, Node: PART 1 USER INTERFACE, Next: Options, Prev: Top, Up: Top++1 PART 1: USER INTERFACE+************************+++File: hledger.info, Node: Options, Next: Environment, Prev: PART 1 USER INTERFACE, Up: Top++2 Options+*********++* Menu:++* General options::+* Command options::+* Command arguments::+* Special characters::+* Unicode characters::+* Regular expressions::+++File: hledger.info, Node: General options, Next: Command options, Up: Options++2.1 General options+===================++To see general usage help, including general options which are supported+by most hledger commands, run ‘hledger -h’.++ General help options:++‘-h --help’++ show general or COMMAND help+‘--man’++ show general or COMMAND user manual with man+‘--info’++ show general or COMMAND user manual with info+‘--version’++ show general or ADDONCMD version+‘--debug[=N]’++ show debug output (levels 1-9, default: 1)++ General input options:++‘-f FILE --file=FILE’++ use a different input file. For stdin, use - (default:+ ‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’)+‘--rules-file=RULESFILE’++ Conversion rules file to use when reading CSV (default: FILE.rules)+‘--separator=CHAR’++ Field separator to expect when reading CSV (default: ’,’)+‘--alias=OLD=NEW’++ rename accounts named OLD to NEW+‘--anon’++ anonymize accounts and payees+‘--pivot FIELDNAME’++ use some other field or tag for the account name+‘-I --ignore-assertions’++ disable balance assertion checks (note: does not disable balance+ assignments)+‘-s --strict’++ do extra error checking (check that all posted accounts are+ declared)++ General reporting options:++‘-b --begin=DATE’++ include postings/txns on or after this date (will be adjusted to+ preceding subperiod start when using a report interval)+‘-e --end=DATE’++ include postings/txns before this date (will be adjusted to+ following subperiod end when using a report interval)+‘-D --daily’++ multiperiod/multicolumn report by day+‘-W --weekly’++ multiperiod/multicolumn report by week+‘-M --monthly’++ multiperiod/multicolumn report by month+‘-Q --quarterly’++ multiperiod/multicolumn report by quarter+‘-Y --yearly’++ multiperiod/multicolumn report by year+‘-p --period=PERIODEXP’++ set start date, end date, and/or reporting interval all at once+ using period expressions syntax+‘--date2’++ match the secondary date instead (see command help for other+ effects)+‘--today=DATE’++ override today’s date (affects relative smart dates, for+ tests/examples)+‘-U --unmarked’++ include only unmarked postings/txns (can combine with -P or -C)+‘-P --pending’++ include only pending postings/txns+‘-C --cleared’++ include only cleared postings/txns+‘-R --real’++ include only non-virtual postings+‘-NUM --depth=NUM’++ hide/aggregate accounts or postings more than NUM levels deep+‘-E --empty’++ show items with zero amount, normally hidden (and vice-versa in+ hledger-ui/hledger-web)+‘-B --cost’++ convert amounts to their cost/selling amount at transaction time+‘-V --market’++ convert amounts to their market value in default valuation+ commodities+‘-X --exchange=COMM’++ convert amounts to their market value in commodity COMM+‘--value’++ convert amounts to cost or market value, more flexibly than+ -B/-V/-X+‘--infer-market-prices’++ use transaction prices (recorded with @ or @@) as additional market+ prices, as if they were P directives+‘--auto’++ apply automated posting rules to modify transactions.+‘--forecast’++ generate future transactions from periodic transaction rules, for+ the next 6 months or till report end date. In hledger-ui, also+ make ordinary future transactions visible.+‘--commodity-style’++ Override the commodity style in the output for the specified+ commodity. For example ’EUR1.000,00’.+‘--color=WHEN (or --colour=WHEN)’++ Should color-supporting commands use ANSI color codes in text+ output. ’auto’ (default): whenever stdout seems to be a+ color-supporting terminal. ’always’ or ’yes’: always, useful eg+ when piping output into ’less -R’. ’never’ or ’no’: never. A+ NO_COLOR environment variable overrides this.+‘--pretty[=WHEN]’++ Show prettier output, e.g. using unicode box-drawing characters.+ Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’+ also work). If you provide an argument you must use ’=’, e.g.+ ’–pretty=yes’.++ When a reporting option appears more than once in the command line,+the last one takes precedence.++ Some reporting options can also be written as query arguments.+++File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: Options++2.2 Command options+===================++To see options for a particular command, including command-specific+options, run: ‘hledger COMMAND -h’.++ Command-specific options must be written after the command name, eg:+‘hledger print -x’.++ Additionally, if the command is an add-on, you may need to put its+options after a double-hyphen, eg: ‘hledger ui -- --watch’. Or, you can+run the add-on executable directly: ‘hledger-ui --watch’.+++File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: Options++2.3 Command arguments+=====================++Most hledger commands accept arguments after the command name, which are+often a query, filtering the data in some way.++ You can save a set of command line options/arguments in a file, and+then reuse them by writing ‘@FILENAME’ as a command line argument. Eg:+‘hledger bal @foo.args’. (To prevent this, eg if you have an argument+that begins with a literal ‘@’, precede it with ‘--’, eg: ‘hledger bal+-- @ARG’).++ Inside the argument file, each line should contain just one option or+argument. Avoid the use of spaces, except inside quotes (or you’ll see+a confusing error). Between a flag and its argument, use = (or+nothing). Bad:++assets depth:2+-X USD++ Good:++assets+depth:2+-X=USD++ For special characters (see below), use one less level of quoting+than you would at the command prompt. Bad:++-X"$"++ Good:++-X$++ See also: Save frequently used options.+++File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: Options++2.4 Special characters+======================++* Menu:++* Single escaping shell metacharacters::+* Double escaping regular expression metacharacters::+* Triple escaping for add-on commands::+* Less escaping::+++File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters++2.4.1 Single escaping (shell metacharacters)+--------------------------------------------++In shell command lines, characters significant to your shell - such as+spaces, ‘<’, ‘>’, ‘(’, ‘)’, ‘|’, ‘$’ and ‘\’ - should be "shell-escaped"+if you want hledger to see them. This is done by enclosing them in+single or double quotes, or by writing a backslash before them. Eg to+match an account name containing a space:++$ hledger register 'credit card'++ or:++$ hledger register credit\ card++ Windows users should keep in mind that ‘cmd’ treats single quote as a+regular character, so you should be using double quotes exclusively.+PowerShell treats both single and double quotes as quotes.+++File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters++2.4.2 Double escaping (regular expression metacharacters)+---------------------------------------------------------++Characters significant in regular expressions (described below) - such+as ‘.’, ‘^’, ‘$’, ‘[’, ‘]’, ‘(’, ‘)’, ‘|’, and ‘\’ - may need to be+"regex-escaped" if you don’t want them to be interpreted by hledger’s+regular expression engine. This is done by writing backslashes before+them, but since backslash is typically also a shell metacharacter, both+shell-escaping and regex-escaping will be needed. Eg to match a literal+‘$’ sign while using the bash shell:++$ hledger balance cur:'\$'++ or:++$ hledger balance cur:\\$+++File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters++2.4.3 Triple escaping (for add-on commands)+-------------------------------------------++When you use hledger to run an external add-on command (described+below), one level of shell-escaping is lost from any options or+arguments intended for by the add-on command, so those need an extra+level of shell-escaping. Eg to match a literal ‘$’ sign while using the+bash shell and running an add-on command (‘ui’):++$ hledger ui cur:'\\$'++ or:++$ hledger ui cur:\\\\$++ If you wondered why _four_ backslashes, perhaps this helps:++unescaped: ‘$’+escaped: ‘\$’+double-escaped: ‘\\$’+triple-escaped: ‘\\\\$’++ Or, you can avoid the extra escaping by running the add-on executable+directly:++$ hledger-ui cur:\\$+++File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters++2.4.4 Less escaping+-------------------++Options and arguments are sometimes used in places other than the shell+command line, where shell-escaping is not needed, so there you should+use one less level of escaping. Those places include:++ • an @argumentfile+ • hledger-ui’s filter field+ • hledger-web’s search form+ • GHCI’s prompt (used by developers).+++File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options++2.5 Unicode characters+======================++hledger is expected to handle non-ascii characters correctly:++ • they should be parsed correctly in input files and on the command+ line, by all hledger tools (add, iadd, hledger-web’s+ search/add/edit forms, etc.)++ • they should be displayed correctly by all hledger tools, and+ on-screen alignment should be preserved.++ This requires a well-configured environment. Here are some tips:++ • A system locale must be configured, and it must be one that can+ decode the characters being used. In bash, you can set a locale+ like this: ‘export LANG=en_US.UTF-8’. There are some more details+ in Troubleshooting. This step is essential - without it, hledger+ will quit on encountering a non-ascii character (as with all+ GHC-compiled programs).++ • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)+ must support unicode++ • the terminal must be using a font which includes the required+ unicode glyphs++ • the terminal should be configured to display wide characters as+ double width (for report alignment)++ • on Windows, for best results you should run hledger in the same+ kind of environment in which it was built. Eg hledger built in the+ standard CMD.EXE environment (like the binaries on our download+ page) might show display problems when run in a cygwin or msys+ terminal, and vice versa. (See eg #961).+++File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: Options++2.6 Regular expressions+=======================++hledger uses regular expressions in a number of places:++ • query terms, on the command line and in the hledger-web search+ form: ‘REGEX’, ‘desc:REGEX’, ‘cur:REGEX’, ‘tag:...=REGEX’+ • CSV rules conditional blocks: ‘if REGEX ...’+ • account alias directive and ‘--alias’ option: ‘alias /REGEX/ =+ REPLACEMENT’, ‘--alias /REGEX/=REPLACEMENT’++ hledger’s regular expressions come from the regex-tdfa library. If+they’re not doing what you expect, it’s important to know exactly what+they support:++ 1. they are case insensitive+ 2. they are infix matching (they do not need to match the entire thing+ being matched)+ 3. they are POSIX ERE (extended regular expressions)+ 4. they also support GNU word boundaries (‘\b’, ‘\B’, ‘\<’, ‘\>’)+ 5. they do not support backreferences; if you write ‘\1’, it will+ match the digit ‘1’. Except when doing text replacement, eg in+ account aliases, where backreferences can be used in the+ replacement string to reference capturing groups in the search+ regexp.+ 6. they do not support mode modifiers (‘(?s)’), character classes+ (‘\w’, ‘\d’), or anything else not mentioned above.++ Some things to note:++ • In the ‘alias’ directive and ‘--alias’ option, regular expressions+ must be enclosed in forward slashes (‘/REGEX/’). Elsewhere in+ hledger, these are not required.++ • In queries, to match a regular expression metacharacter like ‘$’ as+ a literal character, prepend a backslash. Eg to search for amounts+ with the dollar sign in hledger-web, write ‘cur:\$’.++ • On the command line, some metacharacters like ‘$’ have a special+ meaning to the shell and so must be escaped at least once more.+ See Special characters.+++File: hledger.info, Node: Environment, Next: Input, Prev: Options, Up: Top++3 Environment+*************++*LEDGER_FILE* The journal file path when not specified with ‘-f’.++ On unix computers, the default value is: ‘~/.hledger.journal’.++ A more typical value is something like ‘~/finance/YYYY.journal’,+where ‘~/finance’ is a version-controlled finance directory and YYYY is+the current year. Or, ‘~/finance/current.journal’, where+current.journal is a symbolic link to YYYY.journal.++ The usual way to set this permanently is to add a command to one of+your shell’s startup files (eg ‘~/.profile’):++export LEDGER_FILE=~/finance/current.journal`++ On some Mac computers, there is a more thorough way to set+environment variables, that will also affect applications started from+the GUI (eg, Emacs started from a dock icon): In+‘~/.MacOSX/environment.plist’, add an entry like:++{+ "LEDGER_FILE" : "~/finance/current.journal"+}++ For this to take effect you might need to ‘killall Dock’, or reboot.++ On Windows computers, the default value is probably+‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a+command like this in a powershell window (let us know if you need to be+an Administrator, and if this persists across a reboot):++> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"++ Or, change it in settings: see+https://www.java.com/en/download/help/path.html.++ *COLUMNS* The screen width used by the register command. Default:+the full terminal width.++ *NO_COLOR* If this variable exists with any value, hledger will not+use ANSI color codes in terminal output. This is overriden by the+–color/–colour option.+++File: hledger.info, Node: Input, Next: Commands, Prev: Environment, Up: Top++4 Input+*******++hledger reads transactions from one or more data files. The default+data file is ‘$HOME/.hledger.journal’ (or on Windows, something like+‘C:\Users\YOURNAME\.hledger.journal’).++ You can override this with the ‘$LEDGER_FILE’ environment variable:++$ setenv LEDGER_FILE ~/finance/2016.journal+$ hledger stats++ or with one or more ‘-f/--file’ options:++$ hledger -f /some/file -f another_file stats++ The file name ‘-’ means standard input:++$ cat some.journal | hledger -f-++* Menu:++* Data formats::+* Multiple files::+* Strict mode::+++File: hledger.info, Node: Data formats, Next: Multiple files, Up: Input++4.1 Data formats+================++Usually the data file is in hledger’s journal format, but it can be in+any of the supported file formats, which currently are:++Reader: Reads: Used for file+ extensions:+--------------------------------------------------------------------------+‘journal’hledger journal files and some Ledger ‘.journal’ ‘.j’+ journals, for transactions ‘.hledger’ ‘.ledger’+‘timeclock’timeclock files, for precise time ‘.timeclock’+ logging+‘timedot’timedot files, for approximate time ‘.timedot’+ logging+‘csv’ comma/semicolon/tab/other-separated ‘.csv’ ‘.ssv’ ‘.tsv’+ values, for data import++ These formats are described in more detail below.++ hledger detects the format automatically based on the file extensions+shown above. If it can’t recognise the file extension, it assumes+‘journal’ format. So for non-journal files, it’s important to use a+recognised file extension, so as to either read successfully or to show+relevant error messages.++ You can also force a specific reader/format by prefixing the file+path with the format and a colon. Eg, to read a .dat file as csv+format:++$ hledger -f csv:/some/csv-file.dat stats++ Or to read stdin (‘-’) as timeclock format:++$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-+++File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Data formats, Up: Input++4.2 Multiple files+==================++You can specify multiple ‘-f’ options, to read multiple files as one big+journal. There are some limitations with this:++ • most directives do not affect sibling files+ • balance assertions will not see any account balances from previous+ files++ If you need either of those things, you can++ • use a single parent file which includes the others+ • or concatenate the files into one before reading, eg: ‘cat+ a.journal b.journal | hledger -f- CMD’.+++File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input++4.3 Strict mode+===============++hledger checks input files for valid data. By default, the most+important errors are detected, while still accepting easy journal files+without a lot of declarations:++ • Are the input files parseable, with valid syntax ?+ • Are all transactions balanced ?+ • Do all balance assertions pass ?++ With the ‘-s’/‘--strict’ flag, additional checks are performed:++ • Are all accounts posted to, declared with an ‘account’ directive ?+ (Account error checking)+ • Are all commodities declared with a ‘commodity’ directive ?+ (Commodity error checking)+ • Are all commodity conversions declared explicitly ?++ You can use the check command to run individual checks – the ones+listed above and some more.+++File: hledger.info, Node: Commands, Next: Output, Prev: Input, Up: Top++5 Commands+**********++hledger provides a number of built-in subcommands (described below).+Most of these read your data without changing it, and display a report.+A few assist with data entry and management.++ Run ‘hledger’ with no arguments to list the commands available, and+‘hledger CMD’ to run a command. CMD can be the full command name, or+its standard abbreviation shown in the commands list, or any unambiguous+prefix of the name. Eg: ‘hledger bal’.++* Menu:++* Add-on commands::+++File: hledger.info, Node: Add-on commands, Up: Commands++5.1 Add-on commands+===================++Add-on commands are extra subcommands provided by programs or scripts in+your PATH++ • whose name starts with ‘hledger-’+ • whose name ends with a recognised file extension:+ ‘.bat’,‘.com’,‘.exe’, ‘.hs’,‘.lhs’,‘.pl’,‘.py’,‘.rb’,‘.rkt’,‘.sh’+ or none+ • and (on unix, mac) which are executable by the current user.++ Addons can be written in any language, but haskell scripts or+programs have a big advantage: they can use hledger’s library code, for+command-line options, parsing and reporting.++ Several add-on commands are installed by the hledger-install script.+See https://hledger.org/scripts.html for more details.++ Note in a hledger command line, add-on command flags must have a+double dash (‘--’) preceding them. Eg you must write:++$ hledger web -- --serve++ and not:++$ hledger web --serve++ (because the ‘--serve’ flag belongs to ‘hledger-web’, not ‘hledger’).++ The ‘-h/--help’ and ‘--version’ flags don’t require ‘--’.++ If you have any trouble with this, remember you can always run the+add-on program directly, eg:++$ hledger-web --serve+++File: hledger.info, Node: Output, Next: Limitations, Prev: Commands, Up: Top++6 Output+********++* Menu:++* Output destination::+* Output format::+* Commodity styles::+* Colour::+* Box-drawing::+* Debug output::+++File: hledger.info, Node: Output destination, Next: Output format, Up: Output++6.1 Output destination+======================++hledger commands send their output to the terminal by default. You can+of course redirect this, eg into a file, using standard shell syntax:++$ hledger print > foo.txt++ Some commands (print, register, stats, the balance commands) also+provide the ‘-o/--output-file’ option, which does the same thing without+needing the shell. Eg:++$ hledger print -o foo.txt+$ hledger print -o - # write to stdout (the default)+++File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output++6.2 Output format+=================++Some commands offer other kinds of output, not just text on the+terminal. Here are those commands and the formats currently supported:++- txt csv html json sql+-----------------------------------------------------------------------------+aregister Y Y Y Y+balance Y _1_ Y _1_ Y _1,2_ Y+balancesheet Y _1_ Y _1_ Y _1_ Y+balancesheetequity Y _1_ Y _1_ Y _1_ Y+cashflow Y _1_ Y _1_ Y _1_ Y+incomestatement Y _1_ Y _1_ Y _1_ Y+print Y Y Y Y+register Y Y Y++ • _1 Also affected by the balance commands’ ‘--layout’ option._+ • _2 ‘balance’ does not support html output without a report interval+ or with ‘--budget’._++ The output format is selected by the ‘-O/--output-format=FMT’ option:++$ hledger print -O csv # print CSV on stdout++ or by the filename extension of an output file specified with the+‘-o/--output-file=FILE.FMT’ option:++$ hledger balancesheet -o foo.csv # write CSV to foo.csv++ The ‘-O’ option can be combined with ‘-o’ to override the file+extension, if needed:++$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt++ Some notes about the various output formats:++* Menu:++* CSV output::+* HTML output::+* JSON output::+* SQL output::+++File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format++6.2.1 CSV output+----------------++ • In CSV output, digit group marks (such as thousands separators) are+ disabled automatically.+++File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format++6.2.2 HTML output+-----------------++ • HTML output can be styled by an optional ‘hledger.css’ file in the+ same directory.+++File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format++6.2.3 JSON output+-----------------++ • This is not yet much used; real-world feedback is welcome.++ • Our JSON is rather large and verbose, since it is a faithful+ representation of hledger’s internal data types. To understand the+ JSON, read the Haskell type definitions, which are mostly in+ https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.++ • hledger represents quantities as Decimal values storing up to 255+ significant digits, eg for repeating decimals. Such numbers can+ arise in practice (from automatically-calculated transaction+ prices), and would break most JSON consumers. So in JSON, we show+ quantities as simple Numbers with at most 10 decimal places. We+ don’t limit the number of integer digits, but that part is under+ your control. We hope this approach will not cause problems in+ practice; if you find otherwise, please let us know. (Cf #1195)+++File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format++6.2.4 SQL output+----------------++ • This is not yet much used; real-world feedback is welcome.++ • SQL output is expected to work with sqlite, MySQL and PostgreSQL++ • SQL output is structured with the expectations that statements will+ be executed in the empty database. If you already have tables+ created via SQL output of hledger, you would probably want to+ either clear tables of existing data (via ‘delete’ or ‘truncate’+ SQL statements) or drop tables completely as otherwise your+ postings will be duped.+++File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output++6.3 Commodity styles+====================++When displaying amounts, hledger infers a standard display style for+each commodity/currency, as described below in Commodity display style.++ If needed, this can be overridden by a ‘-c/--commodity-style’ option+(except for cost amounts and amounts displayed by the ‘print’ command,+which are always displayed with all decimal digits). For example, the+following will force dollar amounts to be displayed as shown:++$ hledger print -c '$1.000,0'++ This option can repeated to set the display style for multiple+commodities/currencies. Its argument is as described in the commodity+directive.+++File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output++6.4 Colour+==========++In terminal output, some commands can produce colour when the terminal+supports it:++ • if the ‘--color/--colour’ option is given a value of ‘yes’ or+ ‘always’ (or ‘no’ or ‘never’), colour will (or will not) be used;+ • otherwise, if the ‘NO_COLOR’ environment variable is set, colour+ will not be used;+ • otherwise, colour will be used if the output (terminal or file)+ supports it.+++File: hledger.info, Node: Box-drawing, Next: Debug output, Prev: Colour, Up: Output++6.5 Box-drawing+===============++In terminal output, you can enable unicode box-drawing characters to+render prettier tables:++ • if the ‘--pretty’ option is given a value of ‘yes’ or ‘always’ (or+ ‘no’ or ‘never’), unicode characters will (or will not) be used;+ • otherwise, unicode characters will not be used.+++File: hledger.info, Node: Debug output, Prev: Box-drawing, Up: Output++6.6 Debug output+================++We intend hledger to be relatively easy to troubleshoot, introspect and+develop. You can add ‘--debug[=N]’ to any hledger command line to see+additional debug output. N ranges from 1 (least output, the default) to+9 (maximum output). Typically you would start with 1 and increase until+you are seeing enough. Debug output goes to stderr, and is not affected+by ‘-o/--output-file’ (unless you redirect stderr to stdout, eg:+‘2>&1’). It will be interleaved with normal output, which can help+reveal when parts of the code are evaluated. To capture debug output in+a log file instead, you can usually redirect stderr, eg:++hledger bal --debug=3 2>hledger.log+++File: hledger.info, Node: Limitations, Next: Troubleshooting, Prev: Output, Up: Top++7 Limitations+*************++The need to precede add-on command options with ‘--’ when invoked from+hledger is awkward.++ When input data contains non-ascii characters, a suitable system+locale must be configured (or there will be an unhelpful error). Eg on+POSIX, set LANG to something other than C.++ In a Microsoft Windows CMD window, non-ascii characters and colours+are not supported.++ On Windows, non-ascii characters may not display correctly when+running a hledger built in CMD in MSYS/CYGWIN, or vice-versa.++ In a Cygwin/MSYS/Mintty window, the tab key is not supported in+hledger add.++ Not all of Ledger’s journal file syntax is supported. See hledger+and Ledger > Differences > journal format.++ On large data files, hledger is slower and uses more memory than+Ledger.+++File: hledger.info, Node: Troubleshooting, Next: PART 2 DATA FORMATS, Prev: Limitations, Up: Top++8 Troubleshooting+*****************++Here are some issues you might encounter when you run hledger (and+remember you can also seek help from the IRC channel, mail list or bug+tracker):++ *Successfully installed, but "No command ’hledger’ found"*+stack and cabal install binaries into a special directory, which should+be added to your PATH environment variable. Eg on unix-like systems,+that is ~/.local/bin and ~/.cabal/bin respectively.++ *I set a custom LEDGER_FILE, but hledger is still using the default+file*+‘LEDGER_FILE’ should be a real environment variable, not just a shell+variable. The command ‘env | grep LEDGER_FILE’ should show it. You may+need to use ‘export’. Here’s an explanation.++ *Getting errors like "Illegal byte sequence" or "Invalid or+incomplete multibyte or wide character" or "commitAndReleaseBuffer:+invalid argument (invalid character)"*+Programs compiled with GHC (hledger, haskell build tools, etc.) need to+have a UTF-8-aware locale configured in the environment, otherwise they+will fail with these kinds of errors when they encounter non-ascii+characters.++ To fix it, set the LANG environment variable to some locale which+supports UTF-8. The locale you choose must be installed on your system.++ Here’s an example of setting LANG temporarily, on Ubuntu GNU/Linux:++$ file my.journal+my.journal: UTF-8 Unicode text # the file is UTF8-encoded+$ echo $LANG+C # LANG is set to the default locale, which does not support UTF8+$ locale -a # which locales are installed ?+C+en_US.utf8 # here's a UTF8-aware one we can use+POSIX+$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command++ If available, ‘C.UTF-8’ will also work. If your preferred locale+isn’t listed by ‘locale -a’, you might need to install it. Eg on+Ubuntu/Debian:++$ apt-get install language-pack-fr+$ locale -a+C+en_US.utf8+fr_BE.utf8+fr_CA.utf8+fr_CH.utf8+fr_FR.utf8+fr_LU.utf8+POSIX+$ LANG=fr_FR.utf8 hledger -f my.journal print++ Here’s how you could set it permanently, if you use a bash shell:++$ echo "export LANG=en_US.utf8" >>~/.bash_profile+$ bash --login++ Exact spelling and capitalisation may be important. Note the+difference on MacOS (‘UTF-8’, not ‘utf8’). Some platforms (eg ubuntu)+allow variant spellings, but others (eg macos) require it to be exact:++$ locale -a | grep -iE en_us.*utf+en_US.UTF-8+$ LANG=en_US.UTF-8 hledger -f my.journal print+++File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Troubleshooting, Up: Top++9 PART 2: DATA FORMATS+**********************+++File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top++10 Journal+**********++hledger’s default file format, representing a General Journal. Here’s a+cheatsheet/mini-tutorial, or you can skip ahead to About journal format.++* Menu:++* Journal cheatsheet::+* About journal format::+* Comments::+* Transactions::+* Dates::+* Status::+* Code::+* Description::+* Transaction comments::+* Postings::+* Account names::+* Amounts::+* Costs::+* Balance assertions::+* Posting comments::+* Tags::+* Directives::+* account directive::+* alias directive::+* commodity directive::+* decimal-mark directive::+* include directive::+* P directive::+* payee directive::+* tag directive::+* Periodic transactions::+* Other syntax::+++File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal++10.1 Journal cheatsheet+=======================++# Here is the main syntax of hledger's journal format+# (omitting extra Ledger compatibility syntax).+# hledger journals contain comments, directives, and transactions, in any order:++###############################################################################+# 1. Comment lines are for notes or temporarily disabling things.+# They begin with #, ;, or a line containing the word "comment".++# hash comment line+; semicolon comment line+comment+These lines+are commented.+end comment++# Some but not all hledger entries can have same-line comments attached to them,+# from ; (semicolon) to end of line.++###############################################################################+# 2. Directives modify parsing or reports in some way.+# They begin with a word or letter (or symbol).++account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;.+account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX)+alias chkg = assets:checking+commodity $0.00+decimal-mark .+include /dev/null+payee Whole Foods+P 2022-01-01 AAAA $1.40+~ monthly budget goals ; <- 2+ spaces between period expression and description+ expenses:food $400+ expenses:home $1000+ budgeted++###############################################################################+# 3. Transactions are what it's all about; they are dated events,+# usually describing movements of money.+# They begin with a date.++# DATE DESCRIPTION ; This is a transaction comment.+# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment.+# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented.+# ; ^^ At least 2 spaces between account and amount.+# ... ; Any number of postings is allowed. The amounts must balance (sum to 0).++2022-01-01 opening balances are declared this way+ assets:checking $1000 ; Account names can be anything. lower case is easy to type.+ assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common.+ assets:cash:wallet $100 ; : indicates subaccounts.+ liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative.+ equity ; One amount can be left blank; $-1900 is inferred here.++2022-04-15 * (#12345) pay taxes+ ; There can be a ! or * after the date meaning "pending" or "cleared".+ ; There can be a transaction code (text in parentheses) after the date/status.+ ; Amounts' sign represents direction of flow, or credit/debit:+ assets:checking $-500 ; minus means removed from this account (credit)+ expenses:tax:us:2021 $500 ; plus means added to this account (debit)+ ; revenue/expense categories are also "accounts"++Kv+2022-01-01 ; The description is optional.+ ; Any currency/commodity symbols are allowed, on either side.+ assets:cash:wallet GBP -10+ expenses:clothing GBP 10+ assets:gringotts -10 gold+ assets:pouch 10 gold+ revenues:gifts -2 "Liquorice Wands" ; Complex symbols+ assets:bag 2 "Liquorice Wands" ; must be double-quoted.++2022-01-01 Cost in another commodity can be noted with @ or @@+ assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost+ assets:investments 3.0 AAAA @@ $4 ; @@ means total cost+ assets:checking $-7.00++2022-01-02 assert balances+ ; Balances can be asserted for extra error checking, in any transaction.+ assets:investments 0 AAAA = 5.0 AAAA+ assets:pouch 0 gold = 10 gold+ assets:savings $0 = $1000++1999-12-31 Ordering transactions by date is recommended but not required.+ ; Postings are not required.++2022.01.01 These date+2022/1/1 formats are+12/31 also allowed (but consistent YYYY-MM-DD is recommended).+++File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal++10.2 About journal format+=========================++hledger’s usual data source is a plain text file containing journal+entries in hledger journal format. This file represents a standard+accounting general journal. I use file names ending in ‘.journal’, but+that’s not required. The journal file contains a number of transaction+entries, each describing a transfer of money (or any commodity) between+two or more named accounts, in a simple format readable by both hledger+and humans.++ hledger’s journal format is a compatible subset, mostly, of ledger’s+journal format, so hledger can work with compatible ledger journal files+as well. It’s safe, and encouraged, to run both hledger and ledger on+the same journal file, eg to validate the results you’re getting.++ You can use hledger without learning any more about this file; just+use the add or web or import commands to create and update it.++ Many users, though, edit the journal file with a text editor, and+track changes with a version control system such as git. Editor addons+such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and+hledger-vscode for Visual Studio Code, make this easier, adding colour,+formatting, tab completion, and useful commands. See Editor+configuration at hledger.org for the full list.++ Here’s a description of each part of the file format (and hledger’s+data model).++ A hledger journal file can contain three kinds of thing: file+comments, transactions, and/or directives (counting periodic transaction+rules and auto posting rules as directives).+++File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal++10.3 Comments+=============++Lines in the journal will be ignored if they begin with a hash (‘#’) or+a semicolon (‘;’). (See also Other syntax.) hledger will also ignore+regions beginning with a ‘comment’ line and ending with an ‘end comment’+line (or file end). Here’s a suggestion for choosing between them:++ • ‘#’ for top-level notes+ • ‘;’ for commenting out things temporarily+ • ‘comment’ for quickly commenting large regions (remember it’s+ there, or you might get confused)++ Eg:++# a comment line+; another commentline+comment+A multi-line comment block,+continuing until "end comment" directive+or the end of the current file.+end comment++ Some hledger entries can have same-line comments attached to them,+from ; (semicolon) to end of line. See Transaction comments, Posting+comments, and Account comments below.+++File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal++10.4 Transactions+=================++Transactions are the main unit of information in a journal file. They+represent events, typically a movement of some quantity of commodities+between two or more named accounts.++ Each transaction is recorded as a journal entry, beginning with a+simple date in column 0. This can be followed by any of the following+optional fields, separated by spaces:++ • a status character (empty, ‘!’, or ‘*’)+ • a code (any short number or text, enclosed in parentheses)+ • a description (any remaining text until end of line or a semicolon)+ • a comment (any remaining text following a semicolon until end of+ line, and any following indented lines beginning with a semicolon)+ • 0 or more indented _posting_ lines, describing what was transferred+ and the accounts involved (indented comment lines are also allowed,+ but not blank lines or non-indented lines).++ Here’s a simple journal file containing one transaction:++2008/01/01 income+ assets:bank:checking $1+ income:salary $-1+++File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal++10.5 Dates+==========++* Menu:++* Simple dates::+* Posting dates::+++File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates++10.5.1 Simple dates+-------------------++Dates in the journal file use _simple dates_ format: ‘YYYY-MM-DD’ or+‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, with leading zeros optional. The year may+be omitted, in which case it will be inferred from the context: the+current transaction, the default year set with a ‘Y’ directive, or the+current date when the command is run. Some examples: ‘2010-01-31’,+‘2010/01/31’, ‘2010.1.31’, ‘1/31’.++ (The UI also accepts simple dates, as well as the more flexible smart+dates documented in the hledger manual.)+++File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates++10.5.2 Posting dates+--------------------++You can give individual postings a different date from their parent+transaction, by adding a posting comment containing a tag (see below)+like ‘date:DATE’. This is probably the best way to control posting+dates precisely. Eg in this example the expense should appear in May+reports, and the deduction from checking should be reported on 6/1 for+easy bank reconciliation:++2015/5/30+ expenses:food $10 ; food purchased on saturday 5/30+ assets:checking ; bank cleared it on monday, date:6/1++$ hledger -f t.j register food+2015-05-30 expenses:food $10 $10++$ hledger -f t.j register checking+2015-06-01 assets:checking $-10 $-10++ DATE should be a simple date; if the year is not specified it will+use the year of the transaction’s date.+The ‘date:’ tag must have a valid simple date value if it is present, eg+a ‘date:’ tag with no value is not allowed.+++File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal++10.6 Status+===========++Transactions, or individual postings within a transaction, can have a+status mark, which is a single character before the transaction+description or posting account name, separated from it by a space,+indicating one of three statuses:++mark status+ +-----------------+ unmarked+‘!’ pending+‘*’ cleared++ When reporting, you can filter by status with the ‘-U/--unmarked’,+‘-P/--pending’, and ‘-C/--cleared’ flags; or the ‘status:’, ‘status:!’,+and ‘status:*’ queries; or the U, P, C keys in hledger-ui.++ Note, in Ledger and in older versions of hledger, the "unmarked"+state is called "uncleared". As of hledger 1.3 we have renamed it to+unmarked for clarity.++ To replicate Ledger and old hledger’s behaviour of also matching+pending, combine -U and -P.++ Status marks are optional, but can be helpful eg for reconciling with+real-world accounts. Some editor modes provide highlighting and+shortcuts for working with status. Eg in Emacs ledger-mode, you can+toggle transaction status with C-c C-e, or posting status with C-c C-c.++ What "uncleared", "pending", and "cleared" actually mean is up to+you. Here’s one suggestion:++status meaning+--------------------------------------------------------------------------+uncleared recorded but not yet reconciled; needs review+pending tentatively reconciled (if needed, eg during a big+ reconciliation)+cleared complete, reconciled as far as possible, and considered+ correct++ With this scheme, you would use ‘-PC’ to see the current balance at+your bank, ‘-U’ to see things which will probably hit your bank soon+(like uncashed checks), and no flags to see the most up-to-date state of+your finances.+++File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal++10.7 Code+=========++After the status mark, but before the description, you can optionally+write a transaction "code", enclosed in parentheses. This is a good+place to record a check number, or some other important transaction id+or reference number.+++File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal++10.8 Description+================++A transaction’s description is the rest of the line following the date+and status mark (or until a comment begins). Sometimes called the+"narration" in traditional bookkeeping, it can be used for whatever you+wish, or left blank. Transaction descriptions can be queried, unlike+comments.++* Menu:++* Payee and note::+++File: hledger.info, Node: Payee and note, Up: Description++10.8.1 Payee and note+---------------------++You can optionally include a ‘|’ (pipe) character in descriptions to+subdivide the description into separate fields for payee/payer name on+the left (up to the first ‘|’) and an additional note field on the right+(after the first ‘|’). This may be worthwhile if you need to do more+precise querying and pivoting by payee or by note.+++File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal++10.9 Transaction comments+=========================++Text following ‘;’, after a transaction description, and/or on indented+lines immediately below it, form comments for that transaction. They+are reproduced by ‘print’ but otherwise ignored, except they may contain+tags, which are not ignored.++2012-01-01 something ; a transaction comment+ ; a second line of transaction comment+ expenses 1+ assets+++File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal++10.10 Postings+==============++A posting is an addition of some amount to, or removal of some amount+from, an account. Each posting line begins with at least one space or+tab (2 or 4 spaces is common), followed by:++ • (optional) a status character (empty, ‘!’, or ‘*’), followed by a+ space+ • (required) an account name (any text, optionally containing *single+ spaces*, until end of line or a double space)+ • (optional) *two or more spaces* or tabs followed by an amount.++ Positive amounts are being added to the account, negative amounts are+being removed.++ The amounts within a transaction must always sum up to zero. As a+convenience, one amount may be left blank; it will be inferred so as to+balance the transaction.++ Be sure to note the unusual two-space delimiter between account name+and amount. This makes it easy to write account names containing+spaces. But if you accidentally leave only one space (or tab) before+the amount, the amount will be considered part of the account name.+++File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal++10.11 Account names+===================++Accounts are the main way of categorising things in hledger. As in+Double Entry Bookkeeping, they can represent real world accounts (such+as a bank account), or more abstract categories such as "money borrowed+from Frank" or "money spent on electricity".++ You can use any account names you like, but we usually start with the+traditional accounting categories, which in english are ‘assets’,+‘liabilities’, ‘equity’, ‘revenues’, ‘expenses’. (You might see these+referred to as A, L, E, R, X for short.)++ For more precise reporting, we usually divide the top level accounts+into more detailed subaccounts, by writing a full colon between account+name parts. For example, from the account names ‘assets:bank:checking’+and ‘expenses:food’, hledger will infer this hierarchy of five accounts:++assets+assets:bank+assets:bank:checking+expenses+expenses:food++ Shown as an outline, the hierarchical tree structure is more clear:++assets+ bank+ checking+expenses+ food++ hledger reports can summarise the account tree to any depth, so you+can go as deep as you like with subcategories, but keeping your account+names relatively simple may be best when starting out.++ Account names may be capitalised or not; they may contain letters,+numbers, symbols, or single spaces. Note, when an account name and an+amount are written on the same line, they must be separated by *two or+more spaces* (or tabs).++ Parentheses or brackets enclosing the full account name indicate+virtual postings, described below. Parentheses or brackets internal to+the account name have no special meaning.++ Account names can be altered temporarily or permanently by account+aliases.+++File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal++10.12 Amounts+=============++After the account name, there is usually an amount. (Important: between+account name and amount, there must be *two or more spaces*.)++ hledger’s amount format is flexible, supporting several international+formats. Here are some examples. Amounts have a number (the+"quantity"):++1++ ..and usually a currency symbol or commodity name (more on this+below), to the left or right of the quantity, with or without a+separating space:++$1+4000 AAPL+3 "green apples"++ Amounts can be preceded by a minus sign (or a plus sign, though plus+is the default), The sign can be written before or after a left-side+commodity symbol:++-$1+$-1++ One or more spaces between the sign and the number are acceptable+when parsing (but they won’t be displayed in output):+++ $1+$- 1++ Scientific E notation is allowed:++1E-6+EUR 1E3++* Menu:++* Decimal marks digit group marks::+* Commodity::+* Directives influencing number parsing and display::+* Commodity display style::+* Rounding::+++File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts++10.12.1 Decimal marks, digit group marks+----------------------------------------++A _decimal mark_ can be written as a period or a comma:++1.23+1,23456780000009++ In the integer part of the quantity (left of the decimal mark),+groups of digits can optionally be separated by a _digit group mark_ - a+space, comma, or period (different from the decimal mark):++ $1,000,000.00+ EUR 2.000.000,00+INR 9,99,99,999.00+ 1 000 000.9455++ Note, a number containing a single digit group mark and no decimal+mark is ambiguous. Are these digit group marks or decimal marks ?++1,000+1.000++ If you don’t tell it otherwise, hledger will assume both of the above+are decimal marks, parsing both numbers as 1.++ To prevent confusing parsing mistakes and undetected typos,+especially if your data contains digit group marks (eg, thousands+separators), we recommend explicitly declaring the decimal mark+character in each journal file, using a directive at the top of the+file. The ‘decimal-mark’ directive is best, otherwise ‘commodity’+directives will also work. These are described below.+++File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts++10.12.2 Commodity+-----------------++Amounts in hledger have both a "quantity", which is a signed decimal+number, and a "commodity", which is a currency symbol, stock ticker, or+any word or phrase describing something you are tracking.++ If the commodity name contains non-letters (spaces, numbers, or+punctuation), you must always write it inside double quotes (‘"green+apples"’, ‘"ABC123"’).++ If you write just a bare number, that too will have a commodity, with+name ‘""’; we call that the "no-symbol commodity".++ Actually, hledger combines these single-commodity amounts into more+powerful multi-commodity amounts, which are what it works with most of+the time. A multi-commodity amount could be, eg: ‘1 USD, 2 EUR, 3.456+TSLA’. In practice, you will only see multi-commodity amounts in+hledger’s output; you can’t write them directly in the journal file.++ (If you are writing scripts or working with hledger’s internals,+these are the ‘Amount’ and ‘MixedAmount’ types.)+++File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts++10.12.3 Directives influencing number parsing and display+---------------------------------------------------------++You can add ‘decimal-mark’ and ‘commodity’ directives to the journal, to+declare and control these things more explicitly and precisely. These+are described below, but here’s a quick example:++# the decimal mark character used by all amounts in this file (all commodities)+decimal-mark .++# display styles for the $, EUR, INR and no-symbol commodities:+commodity $1,000.00+commodity EUR 1.000,00+commodity INR 9,99,99,999.00+commodity 1 000 000.9455+++File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts++10.12.4 Commodity display style+-------------------------------++For the amounts in each commodity, hledger chooses a consistent display+style to use in most reports. (Exceptions: price amounts, and all+amounts displayed by the ‘print’ command, are displayed with all of+their decimal digits visible.)++ A commodity’s display style is inferred as follows.++ First, if a default commodity is declared with ‘D’, this commodity+and its style is applied to any no-symbol amounts in the journal.++ Then each commodity’s style is inferred from one of the following, in+order of preference:++ • The commodity directive for that commodity (including the no-symbol+ commodity), if any.+ • The amounts in that commodity seen in the journal’s transactions.+ (Posting amounts only; prices and periodic or auto rules are+ ignored, currently.)+ • The built-in fallback style, which looks like this: ‘$1000.00’.+ (Symbol on the left, period decimal mark, two decimal places.)++ A style is inferred from journal amounts as follows:++ • Use the general style (decimal mark, symbol placement) of the first+ amount+ • Use the first-seen digit group style (digit group mark, digit group+ sizes), if any+ • Use the maximum number of decimal places of all.++ Cost amounts don’t affect the commodity display style directly, but+occasionally they can do so indirectly (eg when a posting’s amount is+inferred using a cost). If you find this causing problems, use a+commodity directive to fix the display style.++ To summarise: each commodity’s amounts will be normalised to (a) the+style declared by a ‘commodity’ directive, or (b) the style of the first+posting amount in the journal, with the first-seen digit group style and+the maximum-seen number of decimal places. So if your reports are+showing amounts in a way you don’t like, eg with too many decimal+places, use a commodity directive. Some examples:++# declare euro, dollar, bitcoin and no-symbol commodities and set their +# input number formats and output display styles:+commodity EUR 1.000,+commodity $1000.00+commodity 1000.00000000 BTC+commodity 1 000.++ The inferred commodity style can be overridden by supplying a command+line option.+++File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts++10.12.5 Rounding+----------------++Amounts are stored internally as decimal numbers with up to 255 decimal+places, and displayed with the number of decimal places specified by the+commodity display style. Note, hledger uses banker’s rounding: it+rounds to the nearest even number, eg 0.5 displayed with zero decimal+places is "0").+++File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal++10.13 Costs+===========++After a posting amount, you can note its cost (when buying) or selling+price (when selling) in another commodity, by writing either ‘@+UNITPRICE’ or ‘@@ TOTALPRICE’ after it. This indicates a conversion+transaction, where one commodity is exchanged for another.++ (You might also see this called "transaction price" in hledger docs,+discussions, or code; that term was directionally neutral and reminded+that it is a price specific to a transaction, but we now just call it+"cost", with the understanding that the transaction could be a purchase+or a sale.)++ Costs are usually written explicitly with ‘@’ or ‘@@’, but can also+be inferred automatically for simple multi-commodity transactions.+Note, if costs are inferred, the order of postings is significant; the+first posting will have a cost attached, in the commodity of the second.++ As an example, here are several ways to record purchases of a foreign+currency in hledger, using the cost notation either explicitly or+implicitly:++ 1. Write the price per unit, as ‘@ UNITPRICE’ after the amount:++ 2009/1/1+ assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each+ assets:dollars ; balancing amount is -$135.00++ 2. Write the total price, as ‘@@ TOTALPRICE’ after the amount:++ 2009/1/1+ assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot+ assets:dollars++ 3. Specify amounts for all postings, using exactly two commodities,+ and let hledger infer the price that balances the transaction.+ Note the effect of posting order: the price is added to first+ posting, making it ‘€100 @@ $135’, as in example 2:++ 2009/1/1+ assets:euros €100 ; one hundred euros purchased+ assets:dollars $-135 ; for $135++ Amounts can be converted to cost at report time using the ‘-B/--cost’+flag; this is discussed more in the ˜COST REPORTING section.++* Menu:++* Other cost/lot notations::+++File: hledger.info, Node: Other cost/lot notations, Up: Costs++10.13.1 Other cost/lot notations+--------------------------------++A slight digression for Ledger and Beancount users. Ledger has a number+of cost/lot-related notations:++ • ‘@ UNITCOST’ and ‘@@ TOTALCOST’+ • expresses a conversion rate, as in hledger+ • when buying, also creates a lot than can be selected at+ selling time++ • ‘(@) UNITCOST’ and ‘(@@) TOTALCOST’ (virtual cost)+ • like the above, but also means "this cost was exceptional,+ don’t use it when inferring market prices".++ Currently, hledger treats the above like ‘@’ and ‘@@’; the+parentheses are ignored.++ • ‘{=FIXEDUNITCOST}’ and ‘{{=FIXEDTOTALCOST}}’ (fixed price)+ • when buying, means "this cost is also the fixed price, don’t+ let it fluctuate in value reports"++ • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ (lot price)+ • can be used identically to ‘@ UNITCOST’ and ‘@@ TOTALCOST’,+ also creates a lot+ • when selling, combined with ‘@ ...’, specifies an investment+ lot by its cost basis; does not check if that lot is present++ • and related: ‘[YYYY/MM/DD]’ (lot date)+ • when buying, attaches this acquisition date to the lot+ • when selling, selects a lot by its acquisition date++ • ‘(SOME TEXT)’ (lot note)+ • when buying, attaches this note to the lot+ • when selling, selects a lot by its note++ Currently, hledger accepts any or all of the above in any order after+the posting amount, but ignores them. (This can break transaction+balancing.)++ For Beancount users, the notation and behaviour is different:++ • ‘@ UNITCOST’ and ‘@@ TOTALCOST’+ • expresses a cost without creating a lot, as in hledger+ • when buying (augmenting) or selling (reducing) a lot, combined+ with ‘{...}’: documents the cost/selling price (not used for+ transaction balancing)++ • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’+ • when buying (augmenting), expresses the cost for transaction+ balancing, and also creates a lot with this cost basis+ attached+ • when selling (reducing),+ • selects a lot by its cost basis+ • raises an error if that lot is not present or can not be+ selected unambiguously (depending on booking method+ configured)+ • expresses the selling price for transaction balancing++ Currently, hledger accepts the ‘{UNITCOST}’/‘{{TOTALCOST}}’ notation+but ignores it.++ • variations: ‘{}’, ‘{YYYY-MM-DD}’, ‘{"LABEL"}’, ‘{UNITCOST,+ "LABEL"}’, ‘{UNITCOST, YYYY-MM-DD, "LABEL"}’ etc.++ Currently, hledger rejects these.+++File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal++10.14 Balance assertions+========================++hledger supports Ledger-style balance assertions in journal files.+These look like, for example, ‘= EXPECTEDBALANCE’ following a posting’s+amount. Eg here we assert the expected dollar balance in accounts a and+b after each posting:++2013/1/1+ a $1 =$1+ b =$-1++2013/1/2+ a $1 =$2+ b $-1 =$-2++ After reading a journal file, hledger will check all balance+assertions and report an error if any of them fail. Balance assertions+can protect you from, eg, inadvertently disrupting reconciled balances+while cleaning up old entries. You can disable them temporarily with+the ‘-I/--ignore-assertions’ flag, which can be useful for+troubleshooting or for reading Ledger files. (Note: this flag currently+does not disable balance assignments, described below).++* Menu:++* Assertions and ordering::+* Assertions and multiple included files::+* Assertions and multiple -f files::+* Assertions and commodities::+* Assertions and prices::+* Assertions and subaccounts::+* Assertions and virtual postings::+* Assertions and auto postings::+* Assertions and precision::+++File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions++10.14.1 Assertions and ordering+-------------------------------++hledger sorts an account’s postings and assertions first by date and+then (for postings on the same day) by parse order. Note this is+different from Ledger, which sorts assertions only by parse order.+(Also, Ledger assertions do not see the accumulated effect of repeated+postings to the same account within a transaction.)++ So, hledger balance assertions keep working if you reorder+differently-dated transactions within the journal. But if you reorder+same-dated transactions or postings, assertions might break and require+updating. This order dependence does bring an advantage: precise+control over the order of postings and assertions within a day, so you+can assert intra-day balances.+++File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions++10.14.2 Assertions and multiple included files+----------------------------------------------++Multiple files included with the ‘include’ directive are processed as if+concatenated into one file, preserving their order and the posting order+within each file. It means that balance assertions in later files will+see balance from earlier files.++ And if you have multiple postings to an account on the same day,+split across multiple files, and you want to assert the account’s+balance on that day, you’ll need to put the assertion in the right file+- the last one in the sequence, probably.+++File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions++10.14.3 Assertions and multiple -f files+----------------------------------------++Unlike ‘include’, when multiple files are specified on the command line+with multiple ‘-f/--file’ options, balance assertions will not see+balance from earlier files. This can be useful when you do not want+problems in earlier files to disrupt valid assertions in later files.++ If you do want assertions to see balance from earlier files, use+‘include’, or concatenate the files temporarily.+++File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions++10.14.4 Assertions and commodities+----------------------------------++The asserted balance must be a simple single-commodity amount, and in+fact the assertion checks only this commodity’s balance within the+(possibly multi-commodity) account balance. This is how assertions work+in Ledger also. We could call this a "partial" balance assertion.++ To assert the balance of more than one commodity in an account, you+can write multiple postings, each asserting one commodity’s balance.++ You can make a stronger "total" balance assertion by writing a double+equals sign (‘== EXPECTEDBALANCE’). This asserts that there are no+other commodities in the account besides the asserted one (or at least,+that their balance is 0).++2013/1/1+ a $1+ a 1€+ b $-1+ c -1€++2013/1/2 ; These assertions succeed+ a 0 = $1+ a 0 = 1€+ b 0 == $-1+ c 0 == -1€++2013/1/3 ; This assertion fails as 'a' also contains 1€+ a 0 == $1++ It’s not yet possible to make a complete assertion about a balance+that has multiple commodities. One workaround is to isolate each+commodity into its own subaccount:++2013/1/1+ a:usd $1+ a:euro 1€+ b++2013/1/2+ a 0 == 0+ a:usd 0 == $1+ a:euro 0 == 1€+++File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions++10.14.5 Assertions and prices+-----------------------------++Balance assertions ignore costs, and should normally be written without+one:++2019/1/1+ (a) $1 @ €1 = $1++ We do allow prices to be written there, however, and print shows+them, even though they don’t affect whether the assertion passes or+fails. This is for backward compatibility (hledger’s close command used+to generate balance assertions with prices), and because balance+_assignments_ do use them (see below).+++File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions++10.14.6 Assertions and subaccounts+----------------------------------++The balance assertions above (‘=’ and ‘==’) do not count the balance+from subaccounts; they check the account’s exclusive balance only. You+can assert the balance including subaccounts by writing ‘=*’ or ‘==*’,+eg:++2019/1/1+ equity:opening balances+ checking:a 5+ checking:b 5+ checking 1 ==* 11+++File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions++10.14.7 Assertions and virtual postings+---------------------------------------++Balance assertions always consider both real and virtual postings; they+are not affected by the ‘--real/-R’ flag or ‘real:’ query.+++File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions++10.14.8 Assertions and auto postings+------------------------------------++Balance assertions _are_ affected by the ‘--auto’ flag, which generates+auto postings, which can alter account balances. Because auto postings+are optional in hledger, accounts affected by them effectively have two+balances. But balance assertions can only test one or the other of+these. So to avoid making fragile assertions, either:++ • assert the balance calculated with ‘--auto’, and always use+ ‘--auto’ with that file+ • or assert the balance calculated without ‘--auto’, and never use+ ‘--auto’ with that file+ • or avoid balance assertions on accounts affected by auto postings+ (or avoid auto postings entirely).+++File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions++10.14.9 Assertions and precision+--------------------------------++Balance assertions compare the exactly calculated amounts, which are not+always what is shown by reports. Eg a commodity directive may limit the+display precision, but this will not affect balance assertions. Balance+assertion failure messages show exact amounts.+++File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal++10.15 Posting comments+======================++Text following ‘;’, at the end of a posting line, and/or on indented+lines immediately below it, form comments for that posting. They are+reproduced by ‘print’ but otherwise ignored, except they may contain+tags, which are not ignored.++2012-01-01+ expenses 1 ; a comment for posting 1+ assets+ ; a comment for posting 2+ ; a second comment line for posting 2+++File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal++10.16 Tags+==========++Tags are a way to add extra labels or labelled data to transactions,+postings, or accounts, which you can then search or pivot on.++ They are written as a word (optionally hyphenated) immediately+followed by a full colon, in a transaction or posting or account+directive’s comment. (This is an exception to the usual rule that+things in comments are ignored.) Eg, here four different tags are+recorded: one on the checking account, two on the transaction, and one+on the expenses posting:++account assets:checking ; accounttag:++2017/1/16 bought groceries ; transactiontag-1:+ ; transactiontag-2:+ assets:checking $-1+ expenses:food $1 ; postingtag:++ Postings also inherit tags from their transaction and their account.+And transactions also acquire tags from their postings (and postings’+accounts). So in the example above, the expenses posting effectively+has all four tags (by inheriting from account and transaction), and the+transaction also has all four tags (by acquiring from the expenses+posting).++ You can list tag names with ‘hledger tags [NAMEREGEX]’, or match by+tag name with a ‘tag:NAMEREGEX’ query.++* Menu:++* Tag values::+++File: hledger.info, Node: Tag values, Up: Tags++10.16.1 Tag values+------------------++Tags can have a value, which is any text after the colon up until a+comma or end of line (with surrounding whitespace removed). Note this+means that hledger tag values can not contain commas. Eg in the+following posting, the three tags’ values are "value 1", "value 2", and+"" (empty) respectively:++ expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz++ Note that tags can be repeated, and are additive rather than+overriding: when the same tag name is seen again with a new value, the+new name:value pair is added to the tags. (It is not possible to+override a tag’s value or remove a tag.)++ You can list a tag’s values with ‘hledger tags TAGNAME --values’, or+match by tag value with a ‘tag:NAMEREGEX=VALUEREGEX’ query.+++File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal++10.17 Directives+================++A directive is a line in the journal beginning with a special keyword,+that influences how the journal is processed, how things are displayed,+and so on. hledger’s directives are based on (a subset of) Ledger’s,+but there are many differences, and also some differences between+hledger versions. Here are some more definitions:++ • _subdirective_ - Some directives support subdirectives, written+ indented below the parent directive.++ • _decimal mark_ - The character to interpret as a decimal mark+ (period or comma) when parsing amounts of a commodity.++ • _display style_ - How to display amounts of a commodity in output:+ symbol side and spacing, digit groups, decimal mark, and number of+ decimal places.++ Directives are not required when starting out with hledger, but you+will probably want to add some as your needs grow. Here some key+directives for particular needs:++purpose directives+--------------------------------------------------------------------------+*READING DATA:*+Declare file’s decimal mark to help parse ‘decimal-mark’+amounts accurately+Rewrite account names ‘alias’+Comment out sections of the data ‘comment’+Include extra data files ‘include’+*GENERATING DATA:*+Generate recurring transactions or budget ‘~’+goals+Generate extra postings on transactions ‘=’+*CHECKING FOR ERRORS:*+Define valid entities to provide more ‘account’, ‘commodity’,+error checking ‘payee’+*REPORTING:*+Declare accounts’ type and display order ‘account’+Declare commodity display styles ‘commodity’+Declare market prices ‘P’++* Menu:++* Directive effects::+* Directives and multiple files::+++File: hledger.info, Node: Directive effects, Next: Directives and multiple files, Up: Directives++10.17.1 Directive effects+-------------------------++And here is what each directive does, and which files and journal+entries (transactions) it affects:++directivewhat it does ends+ at+ file+ end?+---------------------------------------------------------------------------+*‘account’*Declares an account, for checking all entries in all files; andN+ its display order and type. Subdirectives: any text, ignored.+*‘alias’*Rewrites account names, in following entries until end of Y+ current file or ‘end aliases’. Command line equivalent:+ ‘--alias’+*‘comment’*Ignores part of the journal file, until end of current file orY+ ‘end comment’.+*‘commodity’*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N+ all amounts in all files 2. the decimal mark for parsing+ amounts of this commodity, in the following entries until end of+ current file (if there is no ‘decimal-mark’ directive) 3. and+ the display style for amounts of this commodity 4. which is+ also the precision to use for balanced-transaction checking in+ this commodity. Takes precedence over ‘D’. Subdirectives:+ ‘format’ (Ledger-compatible syntax). Command line equivalent:+ ‘-c/--commodity-style’+*‘decimal-mark’*Declares the decimal mark, for parsing amounts of all Y+ commodities in following entries until next ‘decimal-mark’ or+ end of current file. Included files can override. Takes+ precedence over ‘commodity’ and ‘D’.+*‘include’*Includes entries and directives from another file, as if theyN+ were written inline. Command line alternative: multiple+ ‘-f/--file’+*‘payee’*Declares a payee name, for checking all entries in all files. N+*‘P’*Declares the market price of a commodity on some date, for value N+ reports.+*‘~’*Declares a periodic transaction rule that generates future N+(tilde)transactions with ‘--forecast’ and budget goals with ‘balance+ --budget’.+Other+syntax:+*‘applyPrepends a common parent account to all account names, in Y+account’*following entries until end of current file or ‘end apply+ account’.+*‘D’*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N+ there is no ‘commodity’ directive for this commodity: its+ decimal mark, balancing precision, and display style, as above.+*‘Y’*Sets a default year to use for any yearless dates, in following Y+ entries until end of current file.+*‘=’*Declares an auto posting rule that generates extra postings on partly+(equals)matched transactions with ‘--auto’, in current, parent, and+ child files (but not sibling files, see #1212).+*OtherOther directives from Ledger’s file format are accepted but+Ledgerignored.+directives*+++File: hledger.info, Node: Directives and multiple files, Prev: Directive effects, Up: Directives++10.17.2 Directives and multiple files+-------------------------------------++If you use multiple ‘-f’/‘--file’ options, or the ‘include’ directive,+hledger will process multiple input files. But directives which affect+input typically have effect only until the end of the file in which they+occur (and on any included files in that region).++ This may seem inconvenient, but it’s intentional; it makes reports+stable and deterministic, independent of the order of input. Otherwise+you could see different numbers if you happened to write -f options in a+different order, or if you moved includes around while cleaning up your+files.++ It can be surprising though; for example, it means that ‘alias’+directives do not affect parent or sibling files (see below).+++File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal++10.18 ‘account’ directive+=========================++‘account’ directives can be used to declare accounts (ie, the places+that amounts are transferred from and to). Though not required, these+declarations can provide several benefits:++ • They can document your intended chart of accounts, providing a+ reference.+ • In strict mode, they restrict which accounts may be posted to by+ transactions, which helps detect typos.+ • They control account display order in reports, allowing+ non-alphabetic sorting (eg Revenues to appear above Expenses).+ • They help with account name completion (in hledger add,+ hledger-web, hledger-iadd, ledger-mode, etc.)+ • They can store additional account information as comments, or as+ tags which can be used to filter or pivot reports.+ • They can help hledger know your accounts’ types (asset, liability,+ equity, revenue, expense), affecting reports like balancesheet and+ incomestatement.++ They are written as the word ‘account’ followed by a hledger-style+account name, eg:++account assets:bank:checking++ Note, however, that accounts declared in account directives are not+allowed to have surrounding brackets and parentheses, unlike accounts+used in postings. So the following journal will not parse:++account (assets:bank:checking)++* Menu:++* Account comments::+* Account subdirectives::+* Account error checking::+* Account display order::+* Account types::+++File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive++10.18.1 Account comments+------------------------++Text following *two or more spaces* and ‘;’ at the end of an account+directive line, and/or following ‘;’ on indented lines immediately below+it, form comments for that account. They are ignored except they may+contain tags, which are not ignored.++ The two-space requirement for same-line account comments is because+‘;’ is allowed in account names.++account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon+ ; next-line comment+ ; some tags - type:A, acctnum:12345+++File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive++10.18.2 Account subdirectives+-----------------------------++Ledger-style indented subdirectives are also accepted, but currently+ignored:++account assets:bank:checking+ format subdirective is ignored+++File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive++10.18.3 Account error checking+------------------------------++By default, accounts need not be declared; they come into existence when+a posting references them. This is convenient, but it means hledger+can’t warn you when you mis-spell an account name in the journal.+Usually you’ll find that error later, as an extra account in balance+reports, or an incorrect balance when reconciling.++ In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will+report an error if any transaction uses an account name that has not+been declared by an account directive. Some notes:++ • The declaration is case-sensitive; transactions must use the+ correct account name capitalisation.+ • The account directive’s scope is "whole file and below" (see+ directives). This means it affects all of the current file, and+ any files it includes, but not parent or sibling files. The+ position of account directives within the file does not matter,+ though it’s usual to put them at the top.+ • Accounts can only be declared in ‘journal’ files, but will affect+ included files of all types.+ • It’s currently not possible to declare "all possible subaccounts"+ with a wildcard; every account posted to must be declared.+++File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive++10.18.4 Account display order+-----------------------------++The order in which account directives are written influences the order+in which accounts appear in reports, hledger-ui, hledger-web etc. By+default accounts appear in alphabetical order, but if you add these+account directives to the journal file:++account assets+account liabilities+account equity+account revenues+account expenses++ those accounts will be displayed in declaration order:++$ hledger accounts -1+assets+liabilities+equity+revenues+expenses++ Any undeclared accounts are displayed last, in alphabetical order.++ Sorting is done at each level of the account tree, within each group+of sibling accounts under the same parent. And currently, this+directive:++account other:zoo++ would influence the position of ‘zoo’ among ‘other’’s subaccounts,+but not the position of ‘other’ among the top-level accounts. This+means:++ • you will sometimes declare parent accounts (eg ‘account other’+ above) that you don’t intend to post to, just to customize their+ display order+ • sibling accounts stay together (you couldn’t display ‘x:y’ in+ between ‘a:b’ and ‘a:c’).+++File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive++10.18.5 Account types+---------------------++hledger knows that accounts come in several types: assets, liabilities,+expenses and so on. This enables easy reports like balancesheet and+incomestatement, and filtering by account type with the ‘type:’ query.++ As a convenience, hledger will detect these account types+automatically if you are using common english-language top-level account+names (described below). But generally we recommend you declare types+explicitly, by adding a ‘type:’ tag to your top-level account+directives. Subaccounts will inherit the type of their parent. The+tag’s value should be one of the five main account types:++ • ‘A’ or ‘Asset’ (things you own)+ • ‘L’ or ‘Liability’ (things you owe)+ • ‘E’ or ‘Equity’ (investment/ownership; balanced counterpart of+ assets & liabilities)+ • ‘R’ or ‘Revenue’ (what you received money from, AKA income;+ technically part of Equity)+ • ‘X’ or ‘Expense’ (what you spend money on; technically part of+ Equity)++ or, it can be (these are used less often):++ • ‘C’ or ‘Cash’ (a subtype of Asset, indicating liquid assets for the+ cashflow report)+ • ‘V’ or ‘Conversion’ (a subtype of Equity, for conversions (see COST+ REPORTING).)++ Here is a typical set of account type declarations:++account assets ; type: A+account liabilities ; type: L+account equity ; type: E+account revenues ; type: R+account expenses ; type: X++account assets:bank ; type: C+account assets:cash ; type: C++account equity:conversion ; type: V++ Here are some tips for working with account types.++ • The rules for inferring types from account names are as follows.+ These are just a convenience that sometimes help new users get+ going; if they don’t work for you, just ignore them and declare+ your account types. See also Regular expressions.++ If account's name contains this (CI) regular expression: | its type is:+ --------------------------------------------------------------------|-------------+ ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash+ ^assets?(:|$) | Asset+ ^(debts?|liabilit(y|ies))(:|$) | Liability+ ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion+ ^equity(:|$) | Equity+ ^(income|revenue)s?(:|$) | Revenue+ ^expenses?(:|$) | Expense++ • If you declare any account types, it’s a good idea to declare an+ account for all of the account types, because a mixture of declared+ and name-inferred types can disrupt certain reports.++ • Certain uses of account aliases can disrupt account types. See+ Rewriting accounts > Aliases and account types.++ • As mentioned above, subaccounts will inherit a type from their+ parent account. More precisely, an account’s type is decided by+ the first of these that exists:++ 1. A ‘type:’ declaration for this account.+ 2. A ‘type:’ declaration in the parent accounts above it,+ preferring the nearest.+ 3. An account type inferred from this account’s name.+ 4. An account type inferred from a parent account’s name,+ preferring the nearest parent.+ 5. Otherwise, it will have no type.++ • For troubleshooting, you can list accounts and their types with:++ $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]+++File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal++10.19 ‘alias’ directive+=======================++You can define account alias rules which rewrite your account names, or+parts of them, before generating reports. This can be useful for:++ • expanding shorthand account names to their full form, allowing+ easier data entry and a less verbose journal+ • adapting old journals to your current chart of accounts+ • experimenting with new account organisations, like a new hierarchy+ • combining two accounts into one, eg to see their sum or difference+ on one line+ • customising reports++ Account aliases also rewrite account names in account directives.+They do not affect account names being entered via hledger add or+hledger-web.++ Account aliases are very powerful. They are generally easy to use+correctly, but you can also generate invalid account names with them;+more on this below.++ See also Rewrite account names.++* Menu:++* Basic aliases::+* Regex aliases::+* Combining aliases::+* Aliases and multiple files::+* end aliases directive::+* Aliases can generate bad account names::+* Aliases and account types::+++File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive++10.19.1 Basic aliases+---------------------++To set an account alias, use the ‘alias’ directive in your journal file.+This affects all subsequent journal entries in the current file or its+included files (but note: not sibling or parent files). The spaces+around the = are optional:++alias OLD = NEW++ Or, you can use the ‘--alias 'OLD=NEW'’ option on the command line.+This affects all entries. It’s useful for trying out aliases+interactively.++ OLD and NEW are case sensitive full account names. hledger will+replace any occurrence of the old account name with the new one.+Subaccounts are also affected. Eg:++alias checking = assets:bank:wells fargo:checking+; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"+++File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive++10.19.2 Regex aliases+---------------------++There is also a more powerful variant that uses a regular expression,+indicated by wrapping the pattern in forward slashes. (This is the only+place where hledger requires forward slashes around a regular+expression.)++ Eg:++alias /REGEX/ = REPLACEMENT++ or:++$ hledger --alias '/REGEX/=REPLACEMENT' ...++ Any part of an account name matched by REGEX will be replaced by+REPLACEMENT. REGEX is case-insensitive as usual.++ If you need to match a forward slash, escape it with a backslash, eg+‘/\/=:’.++ If REGEX contains parenthesised match groups, these can be referenced+by the usual backslash and number in REPLACEMENT:++alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3+; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"++ REPLACEMENT continues to the end of line (or on command line, to end+of option argument), so it can contain trailing whitespace.+++File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive++10.19.3 Combining aliases+-------------------------++You can define as many aliases as you like, using journal directives+and/or command line options.++ Recursive aliases - where an account name is rewritten by one alias,+then by another alias, and so on - are allowed. Each alias sees the+effect of previously applied aliases.++ In such cases it can be important to understand which aliases will be+applied and in which order. For (each account name in) each journal+entry, we apply:++ 1. ‘alias’ directives preceding the journal entry, most recently+ parsed first (ie, reading upward from the journal entry, bottom to+ top)+ 2. ‘--alias’ options, in the order they appeared on the command line+ (left to right).++ In other words, for (an account name in) a given journal entry:++ • the nearest alias declaration before/above the entry is applied+ first+ • the next alias before/above that will be be applied next, and so on+ • aliases defined after/below the entry do not affect it.++ This gives nearby aliases precedence over distant ones, and helps+provide semantic stability - aliases will keep working the same way+independent of which files are being read and in which order.++ In case of trouble, adding ‘--debug=6’ to the command line will show+which aliases are being applied when.+++File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive++10.19.4 Aliases and multiple files+----------------------------------++As explained at Directives and multiple files, ‘alias’ directives do not+affect parent or sibling files. Eg in this command,++hledger -f a.aliases -f b.journal++ account aliases defined in a.aliases will not affect b.journal.+Including the aliases doesn’t work either:++include a.aliases++2020-01-01 ; not affected by a.aliases+ foo 1+ bar++ This means that account aliases should usually be declared at the+start of your top-most file, like this:++alias foo=Foo+alias bar=Bar++2020-01-01 ; affected by aliases above+ foo 1+ bar++include c.journal ; also affected+++File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive++10.19.5 ‘end aliases’ directive+-------------------------------++You can clear (forget) all currently defined aliases (seen in the+journal so far, or defined on the command line) with this directive:++end aliases+++File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive++10.19.6 Aliases can generate bad account names+----------------------------------------------++Be aware that account aliases can produce malformed account names, which+could cause confusing reports or invalid ‘print’ output. For example,+you could erase all account names:++2021-01-01+ a:aa 1+ b++$ hledger print --alias '/.*/='+2021-01-01+ 1++ The above ‘print’ output is not a valid journal. Or you could insert+an illegal double space, causing ‘print’ output that would give a+different journal when reparsed:++2021-01-01+ old 1+ other++$ hledger print --alias old="new USD" | hledger -f- print+2021-01-01+ new USD 1+ other+++File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive++10.19.7 Aliases and account types+---------------------------------++If an account with a type declaration (see Declaring accounts > Account+types) is renamed by an alias, normally the account type remains in+effect.++ However, renaming in a way that reshapes the account tree (eg+renaming parent accounts but not their children, or vice versa) could+prevent child accounts from inheriting the account type of their+parents.++ Secondly, if an account’s type is being inferred from its name,+renaming it by an alias could prevent or alter that.++ If you are using account aliases and the ‘type:’ query is not+matching accounts as you expect, try troubleshooting with the accounts+command, eg something like:++$ hledger accounts --alias assets=bassetts type:a+++File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal++10.20 ‘commodity’ directive+===========================++You can use ‘commodity’ directives to declare your commodities. In fact+the ‘commodity’ directive performs several functions at once:++ 1. It declares commodities which may be used in the journal. This can+ optionally be enforced, providing useful error checking. (Cf+ Commodity error checking)++ 2. It declares which decimal mark character (period or comma), to+ expect when parsing input - useful to disambiguate international+ number formats in your data. Without this, hledger will parse both+ ‘1,000’ and ‘1.000’ as 1. (Cf Amounts)++ 3. It declares how to render the commodity’s amounts when displaying+ output - the decimal mark, any digit group marks, the number of+ decimal places, symbol placement and so on. (Cf Commodity display+ style)++ You will run into one of the problems solved by commodity directives+sooner or later, so we recommend using them, for robust and predictable+parsing and display.++ Generally you should put them at the top of your journal file (since+for function 2, they affect only following amounts, cf #793).++ A commodity directive is just the word ‘commodity’ followed by a+sample amount, like this:++;commodity SAMPLEAMOUNT++commodity $1000.00+commodity 1,000.0000 AAAA ; optional same-line comment++ It may also be written on multiple lines, and use the ‘format’+subdirective, as in Ledger. Note in this case the commodity symbol+appears twice; it must be the same in both places:++;commodity SYMBOL+; format SAMPLEAMOUNT++; display indian rupees with currency name on the left,+; thousands, lakhs and crores comma-separated,+; period as decimal point, and two decimal places.+commodity INR+ format INR 1,00,00,000.00++ Other indented subdirectives are currently ignored.++ Remember that if the commodity symbol contains spaces, numbers, or+punctuation, it must be enclosed in double quotes (cf Commodity).++ The amount’s quantity does not matter; only the format is+significant. It must include a decimal mark - either a period or a+comma - followed by 0 or more decimal digits.++ A few more examples:++# number formats for $, EUR, INR and the no-symbol commodity:+commodity $1,000.00+commodity EUR 1.000,00+commodity INR 9,99,99,999.0+commodity 1 000 000.++ Note hledger normally uses banker’s rounding, so 0.5 displayed with+zero decimal digits is "0". (More at Commodity display style.)++ Even in the presence of commodity directives, the commodity display+style can still be overridden by supplying a command line option.++* Menu:++* Commodity error checking::+++File: hledger.info, Node: Commodity error checking, Up: commodity directive++10.20.1 Commodity error checking+--------------------------------++In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will+report an error if a commodity symbol is used that has not been declared+by a ‘commodity’ directive. This works similarly to account error+checking, see the notes there for more details.++ Note, this disallows amounts without a commodity symbol, because+currently it’s not possible (?) to declare the "no-symbol" commodity+with a directive. This is one exception for convenience: zero amounts+are always allowed to have no commodity symbol.+++File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal++10.21 ‘decimal-mark’ directive+==============================++You can use a ‘decimal-mark’ directive - usually one per file, at the+top of the file - to declare which character represents a decimal mark+when parsing amounts in this file. It can look like++decimal-mark .++ or++decimal-mark ,++ This prevents any ambiguity when parsing numbers in the file, so we+recommend it, especially if the file contains digit group marks (eg+thousands separators).+++File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal++10.22 ‘include’ directive+=========================++You can pull in the content of additional files by writing an include+directive, like this:++include FILEPATH++ Only journal files can include, and only journal, timeclock or+timedot files can be included (not CSV files, currently).++ If the file path does not begin with a slash, it is relative to the+current file’s folder.++ A tilde means home directory, eg: ‘include ~/main.journal’.++ The path may contain glob patterns to match multiple files, eg:+‘include *.journal’.++ There is limited support for recursive wildcards: ‘**/’ (the slash is+required) matches 0 or more subdirectories. It’s not super convenient+since you have to avoid include cycles and including directories, but+this can be done, eg: ‘include */**/*.journal’.++ The path may also be prefixed to force a specific file format,+overriding the file extension (as described in hledger.1 -> Input+files): ‘include timedot:~/notes/2020*.md’.+++File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal++10.23 ‘P’ directive+===================++The ‘P’ directive declares a market price, which is a conversion rate+between two commodities on a certain date. This allows value reports to+convert amounts of one commodity to their value in another, on or after+that date. These prices are often obtained from a stock exchange,+cryptocurrency exchange, the or foreign exchange market.++ The format is:++P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT++ DATE is a simple date, COMMODITY1SYMBOL is the symbol of the+commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and+quantity) of commodity 2 that one unit of commodity 1 is worth on this+date. Examples:++# one euro was worth $1.35 from 2009-01-01 onward:+P 2009-01-01 € $1.35++# and $1.40 from 2010-01-01 onward:+P 2010-01-01 € $1.40++ The ‘-V’, ‘-X’ and ‘--value’ flags use these market prices to show+amount values in another commodity. See Valuation.+++File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal++10.24 ‘payee’ directive+=======================++‘payee PAYEE NAME’++ This directive can be used to declare a limited set of payees which+may appear in transaction descriptions. The "payees" check will report+an error if any transaction refers to a payee that has not been+declared. Eg:++payee Whole Foods++ Any indented subdirectives are currently ignored.+++File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal++10.25 ‘tag’ directive+=====================++‘tag TAGNAME’++ This directive can be used to declare a limited set of tag names+allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg:++tag item-id++ Any indented subdirectives are currently ignored.++ The "tags" check will report an error if any undeclared tag name is+used. It is quite easy to accidentally create a tag through normal use+of colons in comments(#comments]; if you want to prevent this, you can+declare and check your tags .+++File: hledger.info, Node: Periodic transactions, Next: Other syntax, Prev: tag directive, Up: Journal++10.26 Periodic transactions+===========================++The ‘~’ directive declares recurring transactions. Such directives+allow hledger to generate temporary future transactions (visible in+reports, not in the journal file) to help with forecasting or budgeting.++ Periodic transactions can be a little tricky, so before you use them,+read this whole section, or at least these tips:++ 1. Two spaces accidentally added or omitted will cause you trouble -+ read about this below.+ 2. For troubleshooting, show the generated transactions with ‘hledger+ print --forecast tag:generated’ or ‘hledger register --forecast+ tag:generated’.+ 3. Forecasted transactions will begin only after the last+ non-forecasted transaction’s date.+ 4. Forecasted transactions will end 6 months from today, by default.+ See below for the exact start/end rules.+ 5. period expressions can be tricky. Their documentation needs+ improvement, but is worth studying.+ 6. Some period expressions with a repeating interval must begin on a+ natural boundary of that interval. Eg in ‘weekly from DATE’, DATE+ must be a monday. ‘~ weekly from 2019/10/1’ (a tuesday) will give+ an error.+ 7. Other period expressions with an interval are automatically+ expanded to cover a whole number of that interval. (This is done+ to improve reports, but it also affects periodic transactions.+ Yes, it’s a bit inconsistent with the above.) Eg: ‘~ every 10th+ day of month from 2020/01’, which is equivalent to ‘~ every 10th+ day of month from 2020/01/01’, will be adjusted to start on+ 2019/12/10.++* Menu:++* Periodic rule syntax::+* Periodic rules and relative dates::+* Two spaces between period expression and description!::+++File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions++10.26.1 Periodic rule syntax+----------------------------++A periodic transaction rule looks like a normal journal entry, with the+date replaced by a tilde (‘~’) followed by a period expression+(mnemonic: ‘~’ looks like a recurring sine wave.):++# every first of month+~ monthly+ expenses:rent $2000+ assets:bank:checking++# every 15th of month in 2023's first quarter:+~ monthly from 2023-04-15 to 2023-06-16+ expenses:utilities $400+ assets:bank:checking++ The period expression is the same syntax used for specifying+multi-period reports, just interpreted differently; there, it specifies+report periods; here it specifies recurrence dates (the periods’ start+dates).+++File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions++10.26.2 Periodic rules and relative dates+-----------------------------------------++Partial or relative dates (like ‘12/31’, ‘25’, ‘tomorrow’, ‘last week’,+‘next quarter’) are usually not recommended in periodic rules, since the+results will change as time passes. If used, they will be interpreted+relative to, in order of preference:++ 1. the first day of the default year specified by a recent ‘Y’+ directive+ 2. or the date specified with ‘--today’+ 3. or the date on which you are running the report.++ They will not be affected at all by report period or forecast period+dates.+++File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions++10.26.3 Two spaces between period expression and description!+-------------------------------------------------------------++If the period expression is followed by a transaction description, these+must be separated by *two or more spaces*. This helps hledger know+where the period expression ends, so that descriptions can not+accidentally alter their meaning, as in this example:++; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"+; ||+; vv+~ every 2 months in 2020, we will review+ assets:bank:checking $1500+ income:acme inc++ So,++ • Do write two spaces between your period expression and your+ transaction description, if any.+ • Don’t accidentally write two spaces in the middle of your period+ expression.+++File: hledger.info, Node: Other syntax, Prev: Periodic transactions, Up: Journal++10.27 Other syntax+==================++hledger journal format supports quite a few other features, mainly to+make interoperating with or converting from Ledger easier. Note some of+the features below are powerful and can be useful in special cases, but+in general, features in this section are considered less important or+even not recommended for most users. Downsides are mentioned to help+you decide if you want to use them.++* Menu:++* Auto postings::+* Balance assignments::+* Bracketed posting dates::+* D directive::+* apply account directive::+* Y directive::+* Secondary dates::+* Star comments::+* Valuation expressions::+* Virtual postings::+* Other Ledger directives::+++File: hledger.info, Node: Auto postings, Next: Balance assignments, Up: Other syntax++10.27.1 Auto postings+---------------------++The ‘=’ directive declares a rule for automatically adding temporary+extra postings (visible in reports, not in the journal file) to all+transactions matched by a certain query, when you use the ‘--auto’ flag.++ Downsides: depending on generated data for your reports makes your+financial data less portable, less future-proof, and less trustworthy in+an audit. Also, because the feature is optional, other features like+balance assertions can break depending on whether it is on or off.++ An auto posting rule looks a bit like a transaction:++= QUERY+ ACCOUNT AMOUNT+ ...+ ACCOUNT [AMOUNT]++ except the first line is an equals sign (mnemonic: ‘=’ suggests+matching), followed by a query (which matches existing postings), and+each "posting" line describes a posting to be generated, and the posting+amounts can be:++ • a normal amount with a commodity symbol, eg ‘$2’. This will be+ used as-is.+ • a number, eg ‘2’. The commodity symbol (if any) from the matched+ posting will be added to this.+ • a numeric multiplier, eg ‘*2’ (a star followed by a number N). The+ matched posting’s amount (and total price, if any) will be+ multiplied by N.+ • a multiplier with a commodity symbol, eg ‘*$2’ (a star, number N,+ and symbol S). The matched posting’s amount will be multiplied by+ N, and its commodity symbol will be replaced with S.++ Any query term containing spaces must be enclosed in single or double+quotes, as on the command line. Eg, note the quotes around the second+query term below:++= expenses:groceries 'expenses:dining out'+ (budget:funds:dining out) *-1++ Some examples:++; every time I buy food, schedule a dollar donation+= expenses:food+ (liabilities:charity) $-1++; when I buy a gift, also deduct that amount from a budget envelope subaccount+= expenses:gifts+ assets:checking:gifts *-1+ assets:checking *1++2017/12/1+ expenses:food $10+ assets:checking++2017/12/14+ expenses:gifts $20+ assets:checking++$ hledger print --auto+2017-12-01+ expenses:food $10+ assets:checking+ (liabilities:charity) $-1++2017-12-14+ expenses:gifts $20+ assets:checking+ assets:checking:gifts -$20+ assets:checking $20++* Menu:++* Auto postings and multiple files::+* Auto postings and dates::+* Auto postings and transaction balancing / inferred amounts / balance assertions::+* Auto posting tags::+++File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings++10.27.1.1 Auto postings and multiple files+..........................................++An auto posting rule can affect any transaction in the current file, or+in any parent file or child file. Note, currently it will not affect+sibling files (when multiple ‘-f’/‘--file’ are used - see #1212).+++File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings++10.27.1.2 Auto postings and dates+.................................++A posting date (or secondary date) in the matched posting, or (taking+precedence) a posting date in the auto posting rule itself, will also be+used in the generated posting.+++File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings++10.27.1.3 Auto postings and transaction balancing / inferred+............................................................++amounts / balance assertions Currently, auto postings are added:++ • after missing amounts are inferred, and transactions are checked+ for balancedness,+ • but before balance assertions are checked.++ Note this means that journal entries must be balanced both before and+after auto postings are added. This changed in hledger 1.12+; see #893+for background.++ This also means that you cannot have more than one auto-posting with+a missing amount applied to a given transaction, as it will be unable to+infer amounts.+++File: hledger.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings++10.27.1.4 Auto posting tags+...........................++Automated postings will have some extra tags:++ • ‘generated-posting:= QUERY’ - shows this was generated by an auto+ posting rule, and the query+ • ‘_generated-posting:= QUERY’ - a hidden tag, which does not appear+ in hledger’s output. This can be used to match postings generated+ "just now", rather than generated in the past and saved to the+ journal.++ Also, any transaction that has been changed by auto posting rules+will have these tags added:++ • ‘modified:’ - this transaction was modified+ • ‘_modified:’ - a hidden tag not appearing in the comment; this+ transaction was modified "just now".+++File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Prev: Auto postings, Up: Other syntax++10.27.2 Balance assignments+---------------------------++Ledger-style balance assignments are also supported. These are like+balance assertions, but with no posting amount on the left side of the+equals sign; instead it is calculated automatically so as to satisfy the+assertion. This can be a convenience during data entry, eg when setting+opening balances:++; starting a new journal, set asset account balances+2016/1/1 opening balances+ assets:checking = $409.32+ assets:savings = $735.24+ assets:cash = $42+ equity:opening balances++ or when adjusting a balance to reality:++; no cash left; update balance, record any untracked spending as a generic expense+2016/1/15+ assets:cash = $0+ expenses:misc++ The calculated amount depends on the account’s balance in the+commodity at that point (which depends on the previously-dated postings+of the commodity to that account since the last balance assertion or+assignment).++ Downsides: using balance assignments makes your journal less+explicit; to know the exact amount posted, you have to run hledger or do+the calculations yourself, instead of just reading it. Also balance+assignments’ forcing of balances can hide errors. These things make+your financial data less portable, less future-proof, and less+trustworthy in an audit.++* Menu:++* Balance assignments and prices::+++File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments++10.27.2.1 Balance assignments and prices+........................................++A cost in a balance assignment will cause the calculated amount to have+that price attached:++2019/1/1+ (a) = $1 @ €2++$ hledger print --explicit+2019-01-01+ (a) $1 @ €2 = $1 @ €2+++File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax++10.27.3 Bracketed posting dates+-------------------------------++For setting posting dates and secondary posting dates, Ledger’s+bracketed date syntax is also supported: ‘[DATE]’, ‘[DATE=DATE2]’ or+‘[=DATE2]’ in posting comments. hledger will attempt to parse any+square-bracketed sequence of the ‘0123456789/-.=’ characters in this+way. With this syntax, DATE infers its year from the transaction and+DATE2 infers its year from DATE.++ Downsides: another syntax to learn, redundant with hledger’s+‘date:’/‘date2:’ tags, and confusingly similar to Ledger’s lot date+syntax.+++File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax++10.27.4 ‘D’ directive+---------------------++‘D AMOUNT’++ This directive sets a default commodity, to be used for any+subsequent commodityless amounts (ie, plain numbers) seen while parsing+the journal. This effect lasts until the next ‘D’ directive, or the end+of the journal.++ For compatibility/historical reasons, ‘D’ also acts like a+‘commodity’ directive (setting the commodity’s decimal mark for parsing+and display style for output). So its argument is not just a commodity+symbol, but a full amount demonstrating the style. The amount must+include a decimal mark (either period or comma). Eg:++; commodity-less amounts should be treated as dollars+; (and displayed with the dollar sign on the left, thousands separators and two decimal places)+D $1,000.00++1/1+ a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00+ b++ Interactions with other directives:++ For setting a commodity’s display style, a ‘commodity’ directive has+highest priority, then a ‘D’ directive.++ For detecting a commodity’s decimal mark during parsing,+‘decimal-mark’ has highest priority, then ‘commodity’, then ‘D’.++ For checking commodity symbols with the check command, a ‘commodity’+directive is required (‘hledger check commodities’ ignores ‘D’+directives).++ Downsides: omitting commodity symbols makes your financial data less+explicit, less portable, and less trustworthy in an audit. It is+usually an unsustainable shortcut; sooner or later you will want to+track multiple commodities. D is overloaded with functions redundant+with ‘commodity’ and ‘decimal-mark’. And it works differently from+Ledger’s ‘D’.+++File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax++10.27.5 ‘apply account’ directive+---------------------------------++This directive sets a default parent account, which will be prepended to+all accounts in following entries, until an ‘end apply account’+directive or end of current file. Eg:++apply account home++2010/1/1+ food $10+ cash++end apply account++ is equivalent to:++2010/01/01+ home:food $10+ home:cash $-10++ ‘account’ directives are also affected, and so is any ‘include’d+content.++ Account names entered via hledger add or hledger-web are not+affected.++ Account aliases, if any, are applied after the parent account is+prepended.++ Downsides: this can make your financial data less explicit, less+portable, and less trustworthy in an audit.+++File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax++10.27.6 ‘Y’ directive+---------------------++‘Y YEAR’++ or (deprecated backward-compatible forms):++ ‘year YEAR’ ‘apply year YEAR’++ The space is optional. This sets a default year to be used for+subsequent dates which don’t specify a year. Eg:++Y2009 ; set default year to 2009++12/15 ; equivalent to 2009/12/15+ expenses 1+ assets++year 2010 ; change default year to 2010++2009/1/30 ; specifies the year, not affected+ expenses 1+ assets++1/31 ; equivalent to 2010/1/31+ expenses 1+ assets++ Downsides: omitting the year (from primary transaction dates, at+least) makes your financial data less explicit, less portable, and less+trustworthy in an audit. Such dates can get separated from their+corresponding Y directive, eg when evaluating a region of the journal in+your editor. A missing Y directive makes reports dependent on today’s+date.+++File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax++10.27.7 Secondary dates+-----------------------++A secondary date is written after the primary date, following an equals+sign. If the year is omitted, the primary date’s year is assumed. When+running reports, the primary (left) date is used by default, but with+the ‘--date2’ flag (or ‘--aux-date’ or ‘--effective’), the secondary+(right) date will be used instead.++ The meaning of secondary dates is up to you, but it’s best to follow+a consistent rule. Eg "primary = the bank’s clearing date, secondary =+date the transaction was initiated, if different".++ Downsides: makes your financial data more complicated, less portable,+and less trustworthy in an audit. Keeping the meaning of the two dates+consistent requires discipline, and you have to remember which reporting+mode is appropriate for a given report. Posting dates are simpler and+better.+++File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax++10.27.8 Star comments+---------------------++Lines beginning with ‘*’ (star/asterisk) are also comment lines. This+feature allows Emacs users to insert org headings in their journal,+allowing them to fold/unfold/navigate it like an outline when viewed+with org mode.++ Downsides: another, unconventional comment syntax to learn.+Decreases your journal’s portability. And switching to Emacs org mode+just for folding/unfolding meant losing the benefits of ledger mode;+nowadays you can add outshine mode to ledger mode to get folding without+losing ledger mode’s features.+++File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax++10.27.9 Valuation expressions+-----------------------------++Ledger allows a valuation function or value to be written in double+parentheses after an amount. hledger ignores these.+++File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax++10.27.10 Virtual postings+-------------------------++A posting with parentheses around the account name is called a _virtual+posting_ or _unbalanced posting_, which means it is exempt from the+usual rule that a transaction’s postings must balance add up to zero.++ This is not part of double entry bookkeeping, so you might choose to+avoid this feature. Or you can use it sparingly for certain special+cases where it can be convenient. Eg, you could set opening balances+without using a balancing equity account:++2022-01-01 opening balances+ (assets:checking) $1000+ (assets:savings) $2000++ A posting with brackets around the account name is called a _balanced+virtual posting_. The balanced virtual postings in a transaction must+add up to zero (separately from other postings). Eg:++2022-01-01 buy food with cash, update budget envelope subaccounts, & something else+ assets:cash $-10 ; <- these balance each other+ expenses:food $7 ; <-+ expenses:food $3 ; <-+ [assets:checking:budget:food] $-10 ; <- and these balance each other+ [assets:checking:available] $10 ; <-+ (something:else) $5 ; <- this is not required to balance++ Postings whose account names are neither parenthesised nor bracketed+are called _real postings_. You can exclude virtual postings from+reports with the ‘-R/--real’ flag or a ‘real:1’ query.++ Downsides: violates double entry bookkeeping, can be used to avoid+figuring out correct entries, makes your financial data less portable+and less trustworthy in an audit.+++File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax++10.27.11 Other Ledger directives+--------------------------------++These other Ledger directives are currently accepted but ignored. This+allows hledger to read more Ledger files, but be aware that hledger’s+reports may differ from Ledger’s if you use these.++apply fixed COMM AMT+apply tag TAG+assert EXPR+bucket / A ACCT+capture ACCT REGEX+check EXPR+define VAR=EXPR+end apply fixed+end apply tag+end apply year+end tag+eval / expr EXPR+python+ PYTHONCODE+tag NAME+value EXPR+--command-line-flags++ See also https://hledger.org/ledger.html for a detailed+hledger/Ledger syntax comparison.+++File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top++11 CSV+******++hledger can read CSV files (Character Separated Value - usually comma,+semicolon, or tab) containing dated records, automatically converting+each record into a transaction.++ (To learn about _writing_ CSV, see CSV output.)++ For best error messages when reading CSV/TSV/SSV files, make sure+they have a corresponding ‘.csv’, ‘.tsv’ or ‘.ssv’ file extension or use+a hledger file prefix (see File Extension below).++ Each CSV file must be described by a corresponding _rules file_.+This contains rules describing the CSV data (header line, fields layout,+date format etc.), how to construct hledger transactions from it, and+how to categorise transactions based on description or other attributes.++ By default hledger looks for a rules file named like the CSV file+with an extra ‘.rules’ extension, in the same directory. Eg when asked+to read ‘foo/FILE.csv’, hledger looks for ‘foo/FILE.csv.rules’. You can+specify a different rules file with the ‘--rules-file’ option. If no+rules file is found, hledger will create a sample rules file, which+you’ll need to adjust.++ At minimum, the rules file must identify the date and amount fields,+and often it also specifies the date format and how many header lines+there are. Here’s a simple CSV file and a rules file for it:++Date, Description, Id, Amount+12/11/2019, Foo, 123, 10.23++# basic.csv.rules+skip 1+fields date, description, , amount+date-format %d/%m/%Y++$ hledger print -f basic.csv+2019-11-12 Foo+ expenses:unknown 10.23+ income:unknown -10.23++ There’s an introductory Importing CSV data tutorial on hledger.org,+and more CSV rules examples below, and a larger collection at+https://github.com/simonmichael/hledger/tree/master/examples/csv.++* Menu:++* CSV rules cheatsheet::+* separator::+* skip::+* date-format::+* timezone::+* newest-first::+* intra-day-reversed::+* decimal-mark::+* fields list::+* Field assignment::+* Field names::+* if block::+* Matchers::+* if table::+* balance-type::+* include::+* Working with CSV::+* CSV rules examples::+++File: hledger.info, Node: CSV rules cheatsheet, Next: separator, Up: CSV++11.1 CSV rules cheatsheet+=========================++The following kinds of rule can appear in the rules file, in any order.+(Blank lines and lines beginning with ‘#’ or ‘;’ or ‘*’ are ignored.)++*‘separator’* declare the field separator, instead of+ relying on file extension+*‘skip’* skip one or more header lines at start of file+*‘date-format’* declare how to parse CSV dates/date-times+*‘timezone’* declare the time zone of ambiguous CSV+ date-times+*‘newest-first’* improve txn order when: there are multiple+ records, newest first, all with the same date+*‘intra-day-reversed’* improve txn order when: same-day txns are in+ opposite order to the overall file+*‘decimal-mark’* declare the decimal mark used in CSV amounts,+ when ambiguous+*‘fields’ list* name CSV fields for easy reference, and+ optionally assign their values to hledger+ fields+*Field assignment* assign a CSV value or interpolated text value+ to a hledger field+*‘if’ block* conditionally assign values to hledger fields,+ or ‘skip’ a record or ‘end’ (skip rest of+ file)+*‘if’ table* conditionally assign values to hledger fields,+ using compact syntax+*‘balance-type’* select which type of balance+ assertions/assignments to generate+*‘include’* inline another CSV rules file++ Working with CSV tips can be found below, including How CSV rules are+evaluated.+++File: hledger.info, Node: separator, Next: skip, Prev: CSV rules cheatsheet, Up: CSV++11.2 ‘separator’+================++You can use the ‘separator’ rule to read other kinds of+character-separated data. The argument is any single separator+character, or the words ‘tab’ or ‘space’ (case insensitive). Eg, for+comma-separated values (CSV):++separator ,++ or for semicolon-separated values (SSV):++separator ;++ or for tab-separated values (TSV):++separator TAB++ If the input file has a ‘.csv’, ‘.ssv’ or ‘.tsv’ file extension (or a+‘csv:’, ‘ssv:’, ‘tsv:’ prefix), the appropriate separator will be+inferred automatically, and you won’t need this rule.+++File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV++11.3 ‘skip’+===========++skip N++ The word ‘skip’ followed by a number (or no number, meaning 1) tells+hledger to ignore this many non-empty lines at the start of the input+data. (Empty/blank lines are skipped automatically, so you don’t need+to count those.) You’ll need this whenever your CSV data contains+header lines. Header lines skipped in this way are ignored, and not+parsed as CSV.++ ‘skip’ can also be used inside if blocks (described below), to skip+individual data records. Note records skipped in this way are still+required to be valid CSV, even though otherwise ignored.+++File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV++11.4 ‘date-format’+==================++date-format DATEFMT++ This is a helper for the ‘date’ (and ‘date2’) fields. If your CSV+dates are not formatted like ‘YYYY-MM-DD’, ‘YYYY/MM/DD’ or ‘YYYY.MM.DD’,+you’ll need to add a date-format rule describing them with a+strptime-style date parsing pattern - see+https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime.+The pattern must parse the CSV date value completely. Some examples:++# MM/DD/YY+date-format %m/%d/%y++# D/M/YYYY+# The - makes leading zeros optional.+date-format %-d/%-m/%Y++# YYYY-Mmm-DD+date-format %Y-%h-%d++# M/D/YYYY HH:MM AM some other junk+# Note the time and junk must be fully parsed, though only the date is used.+date-format %-m/%-d/%Y %l:%M %p some other junk+++File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV++11.5 ‘timezone’+===============++timezone TIMEZONE++ When CSV contains date-times that are implicitly in some time zone+other than yours, but containing no explicit time zone information, you+can use this rule to declare the CSV’s native time zone, which helps+prevent off-by-one dates.++ When the CSV date-times do contain time zone information, you don’t+need this rule; instead, use ‘%Z’ in ‘date-format’ (or ‘%z’, ‘%EZ’,+‘%Ez’; see the formatTime link above).++ In either of these cases, hledger will do a time-zone-aware+conversion, localising the CSV date-times to your current system time+zone. If you prefer to localise to some other time zone, eg for+reproducibility, you can (on unix at least) set the output timezone with+the TZ environment variable, eg:++$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv++ ‘timezone’ currently does not understand timezone names, except+"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".+For others, use numeric format: +HHMM or -HHMM.+++File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV++11.6 ‘newest-first’+===================++hledger tries to ensure that the generated transactions will be ordered+chronologically, including intra-day transactions. Usually it can+auto-detect how the CSV records are ordered. But if it encounters CSV+where all records are on the same date, it assumes that the records are+oldest first. If in fact the CSV’s records are normally newest first,+like:++2022-10-01, txn 3...+2022-10-01, txn 2...+2022-10-01, txn 1...++ you can add the ‘newest-first’ rule to help hledger generate the+transactions in correct order.++# same-day CSV records are newest first+newest-first+++File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV++11.7 ‘intra-day-reversed’+=========================++CSV records for each day are sometimes ordered in reverse compared to+the overall date order. Eg, here dates are newest first, but the+transactions on each date are oldest first:++2022-10-02, txn 3...+2022-10-02, txn 4...+2022-10-01, txn 1...+2022-10-01, txn 2...++ In this situation, add the ‘intra-day-reversed’ rule, and hledger+will compensate, improving the order of transactions.++# transactions within each day are reversed with respect to the overall date order+intra-day-reversed+++File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV++11.8 ‘decimal-mark’+===================++decimal-mark .++ or:++decimal-mark ,++ hledger automatically accepts either period or comma as a decimal+mark when parsing numbers (cf Amounts). However if any numbers in the+CSV contain digit group marks, such as thousand-separating commas, you+should declare the decimal mark explicitly with this rule, to avoid+misparsed numbers.+++File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV++11.9 ‘fields’ list+==================++fields FIELDNAME1, FIELDNAME2, ...++ A fields list (the word ‘fields’ followed by comma-separated field+names) is optional, but convenient. It does two things:++ 1. It names the CSV field in each column. This can be convenient if+ you are referencing them in other rules, so you can say+ ‘%SomeField’ instead of remembering ‘%13’.++ 2. Whenever you use one of the special hledger field names (described+ below), it assigns the CSV value in this position to that hledger+ field. This is the quickest way to populate hledger’s fields and+ build a transaction.++ Here’s an example that says "use the 1st, 2nd and 4th fields as the+transaction’s date, description and amount; name the last two fields for+later reference; and ignore the others":++fields date, description, , amount, , , somefield, anotherfield++ In a fields list, the separator is always comma; it is unrelated to+the CSV file’s separator. Also:++ • There must be least two items in the list (at least one comma).+ • Field names may not contain spaces. Spaces before/after field+ names are optional.+ • Field names may contain ‘_’ (underscore) or ‘-’ (hyphen).+ • Fields you don’t care about can be given a dummy name or an empty+ name.++ If the CSV contains column headings, it’s convenient to use these for+your field names, suitably modified (eg lower-cased with spaces replaced+by underscores).++ Sometimes you may want to alter a CSV field name to avoid assigning+to a hledger field with the same name. Eg you could call the CSV’s+"balance" field ‘balance_’ to avoid directly setting hledger’s ‘balance’+field (and generating a balance assertion).+++File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV++11.10 Field assignment+======================++HLEDGERFIELD FIELDVALUE++ Field assignments are the more flexible way to assign CSV values to+hledger fields. They can be used instead of or in addition to a fields+list (see above).++ To assign a value to a hledger field, write the field name (any of+the standard hledger field/pseudo-field names, defined below), a space,+followed by a text value on the same line. This text value may+interpolate CSV fields, referenced by their 1-based position in the CSV+record (‘%N’), or by the name they were given in the fields list+(‘%CSVFIELD’).++ Some examples:++# set the amount to the 4th CSV field, with " USD" appended+amount %4 USD++# combine three fields to make a comment, containing note: and date: tags+comment note: %somefield - %anotherfield, date: %1++ Tips:++ • Interpolation strips outer whitespace (so a CSV value like ‘" 1 "’+ becomes ‘1’ when interpolated) (#1051).+ • Interpolations always refer to a CSV field - you can’t interpolate+ a hledger field. (See Referencing other fields below).+++File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV++11.11 Field names+=================++Note the two kinds of field names mentioned here, and used only in+hledger CSV rules files:++ 1. *CSV field names* (‘CSVFIELD’ in these docs): you can optionally+ name the CSV columns for easy reference (since hledger doesn’t yet+ automatically recognise column headings in a CSV file), by writing+ arbitrary names in a ‘fields’ list, eg:++ fields When, What, Some_Id, Net, Total, Foo, Bar++ 2. Special *hledger field names* (‘HLEDGERFIELD’ in these docs): you+ must set at least some of these to generate the hledger transaction+ from a CSV record, by writing them as the left hand side of a field+ assignment, eg:++ date %When+ code %Some_Id+ description %What+ comment %Foo %Bar+ amount1 $ %Total++ or directly in a ‘fields’ list:++ fields date, description, code, , amount1, Foo, Bar+ currency $+ comment %Foo %Bar++ Here are all the special hledger field names available, and what+happens when you assign values to them:++* Menu:++* date field::+* date2 field::+* status field::+* code field::+* description field::+* comment field::+* account field::+* amount field::+* currency field::+* balance field::+++File: hledger.info, Node: date field, Next: date2 field, Up: Field names++11.11.1 date field+------------------++Assigning to ‘date’ sets the transaction date.+++File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names++11.11.2 date2 field+-------------------++‘date2’ sets the transaction’s secondary date, if any.+++File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names++11.11.3 status field+--------------------++‘status’ sets the transaction’s status, if any.+++File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names++11.11.4 code field+------------------++‘code’ sets the transaction’s code, if any.+++File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names++11.11.5 description field+-------------------------++‘description’ sets the transaction’s description, if any.+++File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names++11.11.6 comment field+---------------------++‘comment’ sets the transaction’s comment, if any.++ ‘commentN’, where N is a number, sets the Nth posting’s comment.++ You can assign multi-line comments by writing literal ‘\n’ in the+code. A comment starting with ‘\n’ will begin on a new line.++ Comments can contain tags, as usual.+++File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names++11.11.7 account field+---------------------++Assigning to ‘accountN’, where N is 1 to 99, sets the account name of+the Nth posting, and causes that posting to be generated.++ Most often there are two postings, so you’ll want to set ‘account1’+and ‘account2’. Typically ‘account1’ is associated with the CSV file,+and is set once with a top-level assignment, while ‘account2’ is set+based on each transaction’s description, in conditional rules.++ If a posting’s account name is left unset but its amount is set (see+below), a default account name will be chosen (like "expenses:unknown"+or "income:unknown").+++File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names++11.11.8 amount field+--------------------++There are several "amount" field name variants, useful for different+situations:++ • ‘amountN’ sets the amount of the Nth posting, and causes that+ posting to be generated. By assigning to ‘amount1’, ‘amount2’, ...+ etc. you can generate up to 99 postings. Posting numbers don’t+ have to be consecutive; in certain situations using a high number+ might be helpful to influence the layout of postings.++ • ‘amountN-in’ and ‘amountN-out’ should be used instead, as a pair,+ when and only when the amount must be obtained from two CSV fields.+ Eg when the CSV has separate Debit and Credit fields instead of a+ single Amount field. Note:++ • Don’t think "-in is for the first posting and -out is for the+ second posting" - that’s not correct. Think: "‘amountN-in’+ and ‘amountN-out’ together detect the amount for posting N, by+ inspecting two CSV fields at once."+ • hledger assumes both CSV fields are unsigned, and will+ automatically negate the -out value.+ • It also expects that at least one of the values is empty or+ zero, so it knows which one to ignore. If that’s not the case+ you’ll need an if rule (see Setting amounts below).++ • ‘amount’, with no posting number (and similarly, ‘amount-in’ and+ ‘amount-out’ with no number) are an older syntax. We keep them for+ backwards compatibility, and because they have special behaviour+ that is sometimes convenient:++ • They set the amount of posting 1 and (negated) the amount of+ posting 2.+ • Posting 2’s amount will be converted to cost if it has a cost+ price.+ • Any of the newer rules for posting 1 or 2 (like ‘amount1’, or+ ‘amount2-in’ and ‘amount2-out’) will take precedence. This+ allows incrementally migrating old rules files to the new+ syntax.++ There’s more to say about amount-setting that doesn’t fit here;+please see also "Setting amounts" below.+++File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names++11.11.9 currency field+----------------------++‘currency’ sets a currency symbol, to be prepended to all postings’+amounts. You can use this if the CSV amounts do not have a currency+symbol, eg if it is in a separate column.++ ‘currencyN’ prepends a currency symbol to just the Nth posting’s+amount.+++File: hledger.info, Node: balance field, Prev: currency field, Up: Field names++11.11.10 balance field+----------------------++‘balanceN’ sets a balance assertion amount (or if the posting amount is+left empty, a balance assignment) on posting N.++ ‘balance’ is a compatibility spelling for hledger <1.17; it is+equivalent to ‘balance1’.++ You can adjust the type of assertion/assignment with the+‘balance-type’ rule (see below).++ See Tips below for more about setting amounts and currency.+++File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV++11.12 ‘if’ block+================++Rules can be applied conditionally, depending on patterns in the CSV+data. This allows flexibility; in particular, it is how you can+categorise transactions, selecting an appropriate account name based on+their description (for example). There are two ways to write+conditional rules: "if blocks", described here, and "if tables",+described below.++ An if block is the word ‘if’ and one or more "matcher" expressions+(can be a word or phrase), one per line, starting either on the same or+next line; followed by one or more indented rules. Eg,++if MATCHER+ RULE++ or++if+MATCHER+MATCHER+MATCHER+ RULE+ RULE++ If any of the matchers succeeds, all of the indented rules will be+applied. They are usually field assignments, but the following special+rules may also be used within an if block:++ • ‘skip’ - skips the matched CSV record (generating no transaction+ from it)+ • ‘end’ - skips the rest of the current CSV file.++ Some examples:++# if the record contains "groceries", set account2 to "expenses:groceries"+if groceries+ account2 expenses:groceries++# if the record contains any of these phrases, set account2 and a transaction comment as shown+if+monthly service fee+atm transaction fee+banking thru software+ account2 expenses:business:banking+ comment XXX deductible ? check it++# if an empty record is seen (assuming five fields), ignore the rest of the CSV file+if ,,,,+ end+++File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV++11.13 Matchers+==============++There are two kinds:++ 1. A record matcher is a word or single-line text fragment or regular+ expression (‘REGEX’), which hledger will try to match+ case-insensitively anywhere within the CSV record.+ Eg: ‘whole foods’++ 2. A field matcher is preceded with a percent sign and CSV field name+ (‘%CSVFIELD REGEX’). hledger will try to match these just within+ the named CSV field.+ Eg: ‘%date 2023’++ The regular expression is (as usual in hledger) a POSIX extended+regular expression, that also supports GNU word boundaries (‘\b’, ‘\B’,+‘\<’, ‘\>’), and nothing else. If you have trouble, see "Regular+expressions" in the hledger manual+(https://hledger.org/hledger.html#regular-expressions).++ With record matchers, it’s important to know that the record matched+is not the original CSV record, but a modified one: separators will be+converted to commas, and enclosing double quotes (but not enclosing+whitespace) are removed. So for example, when reading an SSV file, if+the original record was:++2020-01-01; "Acme, Inc."; 1,000++ the regex would see, and try to match, this modified record text:++2020-01-01,Acme, Inc., 1,000++ When an if block has multiple matchers, they are combined as follows:++ • By default they are OR’d (any one of them can match)+ • When a matcher is preceded by ampersand (‘&’) it will be AND’ed+ with the previous matcher (both of them must match).++ There’s not yet an easy syntax to negate a matcher.+++File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV++11.14 ‘if’ table+================++"if tables" are an alternative to if blocks; they can express many+matchers and field assignments in a more compact tabular format, like+this:++if,HLEDGERFIELD1,HLEDGERFIELD2,...+MATCHERA,VALUE1,VALUE2,...+MATCHERB,VALUE1,VALUE2,...+MATCHERC,VALUE1,VALUE2,...+<empty line>++ The first character after ‘if’ is taken to be the separator for the+rest of the table. It should be a non-alphanumeric character like ‘,’+or ‘|’ that does not appear anywhere else in the table. (Note: it is+unrelated to the CSV file’s separator.) Whitespace can be used in the+matcher lines for readability, but not in the if line currently. The+table must be terminated by an empty line (or end of file). Each line+must contain the same number of separators; empty values are allowed.++ The above means: try all of the matchers; whenever a matcher+succeeds, assign all of the values on that line to the corresponding+hledger fields; later lines can overrider earlier ones. It is+equivalent to this sequence of if blocks:++if MATCHERA+ HLEDGERFIELD1 VALUE1+ HLEDGERFIELD2 VALUE2+ ...++if MATCHERB+ HLEDGERFIELD1 VALUE1+ HLEDGERFIELD2 VALUE2+ ...++if MATCHERC+ HLEDGERFIELD1 VALUE1+ HLEDGERFIELD2 VALUE2+ ...++ Example:++if,account2,comment+atm transaction fee,expenses:business:banking,deductible? check it+%description groceries,expenses:groceries,+2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out+++File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV++11.15 ‘balance-type’+====================++Balance assertions generated by assigning to balanceN are of the simple+‘=’ type by default, which is a single-commodity, subaccount-excluding+assertion. You may find the subaccount-including variants more useful,+eg if you have created some virtual subaccounts of checking to help with+budgeting. You can select a different type of assertion with the+‘balance-type’ rule:++# balance assertions will consider all commodities and all subaccounts+balance-type ==*++ Here are the balance assertion types for quick reference:++= single commodity, exclude subaccounts+=* single commodity, include subaccounts+== multi commodity, exclude subaccounts+==* multi commodity, include subaccounts+++File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV++11.16 ‘include’+===============++include RULESFILE++ This includes the contents of another CSV rules file at this point.+‘RULESFILE’ is an absolute file path or a path relative to the current+file’s directory. This can be useful for sharing common rules between+several rules files, eg:++# someaccount.csv.rules++## someaccount-specific rules+fields date,description,amount+account1 assets:someaccount+account2 expenses:misc++## common rules+include categorisation.rules+++File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV++11.17 Working with CSV+======================++Some tips:++* Menu:++* Rapid feedback::+* Valid CSV::+* File Extension::+* Reading CSV from standard input::+* Reading multiple CSV files::+* Valid transactions::+* Deduplicating importing::+* Setting amounts::+* Amount signs::+* Setting currency/commodity::+* Amount decimal places::+* Referencing other fields::+* How CSV rules are evaluated::+* Well factored rules::+++File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV++11.17.1 Rapid feedback+----------------------++It’s a good idea to get rapid feedback while creating/troubleshooting+CSV rules. Here’s a good way, using entr from eradman.com/entrproject:++$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'++ A desc: query (eg) is used to select just one, or a few, transactions+of interest. "bash -c" is used to run multiple commands, so we can echo+a separator each time the command re-runs, making it easier to read the+output.+++File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV++11.17.2 Valid CSV+-----------------++Note that hledger will only accept valid CSV conforming to RFC 4180, and+equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab+as separators). This means, eg:++ • Values may be enclosed in double quotes, or not. Enclosing in+ single quotes is not allowed. (Eg ‘'A','B'’ is rejected.)+ • When values are enclosed in double quotes, spaces outside the+ quotes are not allowed. (Eg ‘"A", "B"’ is rejected.)+ • When values are not enclosed in quotes, they may not contain double+ quotes. (Eg ‘A"A, B’ is rejected.)++ If your CSV/SSV/TSV is not valid in this sense, you’ll need to+transform it before reading with hledger. Try using sed, or a more+permissive CSV parser like python’s csv lib.+++File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV++11.17.3 File Extension+----------------------++To help hledger choose the CSV file reader and show the right error+messages (and choose the right field separator character by default),+it’s best if CSV/SSV/TSV files are named with a ‘.csv’, ‘.ssv’ or ‘.tsv’+filename extension. (More about this at Data formats.)++ When reading files with the "wrong" extension, you can ensure the CSV+reader (and the default field separator) by prefixing the file path with+‘csv:’, ‘ssv:’ or ‘tsv:’: Eg:++$ hledger -f ssv:foo.dat print++ You can also override the default field separator with a separator+rule if needed.+++File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV++11.17.4 Reading CSV from standard input+---------------------------------------++You’ll need the file format prefix when reading CSV from stdin also,+since hledger assumes journal format by default. Eg:++$ cat foo.dat | hledger -f ssv:- print+++File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Reading CSV from standard input, Up: Working with CSV++11.17.5 Reading multiple CSV files+----------------------------------++If you use multiple ‘-f’ options to read multiple CSV files at once,+hledger will look for a correspondingly-named rules file for each CSV+file. But if you use the ‘--rules-file’ option, that rules file will be+used for all the CSV files.+++File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Working with CSV++11.17.6 Valid transactions+--------------------------++After reading a CSV file, hledger post-processes and validates the+generated journal entries as it would for a journal file - balancing+them, applying balance assignments, and canonicalising amount styles.+Any errors at this stage will be reported in the usual way, displaying+the problem entry.++ There is one exception: balance assertions, if you have generated+them, will not be checked, since normally these will work only when the+CSV data is part of the main journal. If you do need to check balance+assertions generated from CSV right away, pipe into another hledger:++$ hledger -f file.csv print | hledger -f- print+++File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV++11.17.7 Deduplicating, importing+--------------------------------++When you download a CSV file periodically, eg to get your latest bank+transactions, the new file may overlap with the old one, containing some+of the same records.++ The import command will (a) detect the new transactions, and (b)+append just those transactions to your main journal. It is idempotent,+so you don’t have to remember how many times you ran it or with which+version of the CSV. (It keeps state in a hidden ‘.latest.FILE.csv’+file.) This is the easiest way to import CSV data. Eg:++# download the latest CSV files, then run this command.+# Note, no -f flags needed here.+$ hledger import *.csv [--dry]++ This method works for most CSV files. (Where records have a stable+chronological order, and new records appear only at the new end.)++ A number of other tools and workflows, hledger-specific and+otherwise, exist for converting, deduplicating, classifying and managing+CSV data. See:++ • https://hledger.org/cookbook.html#setups-and-workflows+ • https://plaintextaccounting.org -> data import/conversion+++File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV++11.17.8 Setting amounts+-----------------------++Continuing from amount field above, here are more tips on handling+various amount-setting situations:++ 1. *If the amount is in a single CSV field:*++ a. *If its sign indicates direction of flow:*+ Assign it to ‘amountN’, to set the Nth posting’s amount. N is+ usually 1 or 2 but can go up to 99.++ b. *If another field indicates direction of flow:*+ Use one or more conditional rules to set the appropriate+ amount sign. Eg:++ # assume a withdrawal unless Type contains "deposit":+ amount1 -%Amount+ if %Type deposit+ amount1 %Amount++ 2. *If the amount is in one of two CSV fields (eg Debit and Credit):*++ a. *If both fields are unsigned:*+ Assign the fields to ‘amountN-in’ and ‘amountN-out’. This+ sets posting N’s amount to whichever of these has a non-zero+ value. If it’s the -out value, the amount will be negated.++ b. *If either field is signed:*+ Use a conditional rule to flip the sign when needed. Eg+ below, the -out value already has a minus sign so we undo+ hledger’s automatic negating by negating once more (but only+ if the field is non-empty, so that we don’t leave a minus sign+ by itself):++ fields date, description, amount1-in, amount1-out+ if %amount1-out [1-9]+ amount1-out -%amount1-out++ c. *If both fields can contain a non-zero value (or both can be+ empty):*+ The -in/-out rules normally choose the value which is+ non-zero/non-empty. Some value pairs can be ambiguous, such+ as ‘1’ and ‘none’. For such cases, use conditional rules to+ help select the amount. Eg, to handle the above you could+ select the value containing non-zero digits:++ fields date, description, in, out+ if %in [1-9]+ amount1 %in+ if %out [1-9]+ amount1 %out++ 3. *If you want posting 2’s amount converted to cost:*+ Use the unnumbered ‘amount’ (or ‘amount-in’ and ‘amount-out’)+ syntax.++ 4. *If the CSV has only balance amounts, not transaction amounts:*+ Assign to ‘balanceN’, to set a balance assignment on the Nth+ posting, causing the posting’s amount to be calculated+ automatically. ‘balance’ with no number is equivalent to+ ‘balance1’. In this situation hledger is more likely to guess the+ wrong default account name, so you may need to set that explicitly.+++File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV++11.17.9 Amount signs+--------------------++There is some special handling for amount signs, to simplify parsing and+sign-flipping:++ • *If an amount value begins with a plus sign:*+ that will be removed: ‘+AMT’ becomes ‘AMT’++ • *If an amount value is parenthesised:*+ it will be de-parenthesised and sign-flipped: ‘(AMT)’ becomes+ ‘-AMT’++ • *If an amount value has two minus signs (or two sets of+ parentheses, or a minus sign and parentheses):*+ they cancel out and will be removed: ‘--AMT’ or ‘-(AMT)’ becomes+ ‘AMT’++ • *If an amount value contains just a sign (or just a set of+ parentheses):*+ that is removed, making it an empty value. ‘"+"’ or ‘"-"’ or+ ‘"()"’ becomes ‘""’.+++File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV++11.17.10 Setting currency/commodity+-----------------------------------++If the currency/commodity symbol is included in the CSV’s amount+field(s):++2020-01-01,foo,$123.00++ you don’t have to do anything special for the commodity symbol, it+will be assigned as part of the amount. Eg:++fields date,description,amount++2020-01-01 foo+ expenses:unknown $123.00+ income:unknown $-123.00++ If the currency is provided as a separate CSV field:++2020-01-01,foo,USD,123.00++ You can assign that to the ‘currency’ pseudo-field, which has the+special effect of prepending itself to every amount in the transaction+(on the left, with no separating space):++fields date,description,currency,amount++2020-01-01 foo+ expenses:unknown USD123.00+ income:unknown USD-123.00++ Or, you can use a field assignment to construct the amount yourself,+with more control. Eg to put the symbol on the right, and separated by+a space:++fields date,description,cur,amt+amount %amt %cur++2020-01-01 foo+ expenses:unknown 123.00 USD+ income:unknown -123.00 USD++ Note we used a temporary field name (‘cur’) that is not ‘currency’ -+that would trigger the prepending effect, which we don’t want here.+++File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV++11.17.11 Amount decimal places+------------------------------++Like amounts in a journal file, the amounts generated by CSV rules like+‘amount1’ influence commodity display styles, such as the number of+decimal places displayed in reports.++ The original amounts as written in the CSV file do not affect display+style (because we don’t yet reliably know their commodity).+++File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV++11.17.12 Referencing other fields+---------------------------------++In field assignments, you can interpolate only CSV fields, not hledger+fields. In the example below, there’s both a CSV field and a hledger+field named amount1, but %amount1 always means the CSV field, not the+hledger field:++# Name the third CSV field "amount1"+fields date,description,amount1++# Set hledger's amount1 to the CSV amount1 field followed by USD+amount1 %amount1 USD++# Set comment to the CSV amount1 (not the amount1 assigned above)+comment %amount1++ Here, since there’s no CSV amount1 field, %amount1 will produce a+literal "amount1":++fields date,description,csvamount+amount1 %csvamount USD+# Can't interpolate amount1 here+comment %amount1++ When there are multiple field assignments to the same hledger field,+only the last one takes effect. Here, comment’s value will be be B, or+C if "something" is matched, but never A:++comment A+comment B+if something+ comment C+++File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV++11.17.13 How CSV rules are evaluated+------------------------------------++Here’s how to think of CSV rules being evaluated (if you really need+to). First,++ • ‘include’ - all includes are inlined, from top to bottom, depth+ first. (At each include point the file is inlined and scanned for+ further includes, recursively, before proceeding.)++ Then "global" rules are evaluated, top to bottom. If a rule is+repeated, the last one wins:++ • ‘skip’ (at top level)+ • ‘date-format’+ • ‘newest-first’+ • ‘fields’ - names the CSV fields, optionally sets up initial+ assignments to hledger fields++ Then for each CSV record in turn:++ • test all ‘if’ blocks. If any of them contain a ‘end’ rule, skip+ all remaining CSV records. Otherwise if any of them contain a+ ‘skip’ rule, skip that many CSV records. If there are multiple+ matched ‘skip’ rules, the first one wins.+ • collect all field assignments at top level and in matched ‘if’+ blocks. When there are multiple assignments for a field, keep only+ the last one.+ • compute a value for each hledger field - either the one that was+ assigned to it (and interpolate the %CSVFIELD references), or a+ default+ • generate a hledger transaction (journal entry) from these values.++ This is all part of the CSV reader, one of several readers hledger+can use to parse input files. When all files have been read+successfully, the transactions are passed as input to whichever hledger+command the user specified.+++File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV++11.17.14 Well factored rules+----------------------------++Some things than can help reduce duplication and complexity in rules+files:++ • Extracting common rules usable with multiple CSV files into a+ ‘common.rules’, and adding ‘include common.rules’ to each CSV’s+ rules file.++ • Splitting if blocks into smaller if blocks, extracting the+ frequently used parts.+++File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV++11.18 CSV rules examples+========================++* Menu:++* Bank of Ireland::+* Coinbase::+* Amazon::+* Paypal::+++File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples++11.18.1 Bank of Ireland+-----------------------++Here’s a CSV with two amount fields (Debit and Credit), and a balance+field, which we can use to add balance assertions, which is not+necessary but provides extra error checking:++Date,Details,Debit,Credit,Balance+07/12/2012,LODGMENT 529898,,10.0,131.21+07/12/2012,PAYMENT,5,,126++# bankofireland-checking.csv.rules++# skip the header line+skip++# name the csv fields, and assign some of them as journal entry fields+fields date, description, amount-out, amount-in, balance++# We generate balance assertions by assigning to "balance"+# above, but you may sometimes need to remove these because:+#+# - the CSV balance differs from the true balance,+# by up to 0.0000000000005 in my experience+#+# - it is sometimes calculated based on non-chronological ordering,+# eg when multiple transactions clear on the same day++# date is in UK/Ireland format+date-format %d/%m/%Y++# set the currency+currency EUR++# set the base account for all txns+account1 assets:bank:boi:checking++$ hledger -f bankofireland-checking.csv print+2012-12-07 LODGMENT 529898+ assets:bank:boi:checking EUR10.0 = EUR131.2+ income:unknown EUR-10.0++2012-12-07 PAYMENT+ assets:bank:boi:checking EUR-5.0 = EUR126.0+ expenses:unknown EUR5.0++ The balance assertions don’t raise an error above, because we’re+reading directly from CSV, but they will be checked if these entries are+imported into a journal file.+++File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples++11.18.2 Coinbase+----------------++A simple example with some CSV from Coinbase. The spot price is+recorded using cost notation. The legacy ‘amount’ field name+conveniently sets amount 2 (posting 2’s amount) to the total cost.++# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes+# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"++# coinbase.csv.rules+skip 1+fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes+date %Timestamp+date-format %Y-%m-%dT%T%Z+description %Notes+account1 assets:coinbase:cc+amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency++$ hledger print -f coinbase.csv+2021-12-30 Received 100.00 USDC from an external account+ assets:coinbase:cc 100 USDC @ 0.740000 GBP+ income:unknown -74.000000 GBP+++File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples++11.18.3 Amazon+--------------++Here we convert amazon.com order history, and use an if block to+generate a third posting if there’s a fee. (In practice you’d probably+get this data from your bank instead, but it’s an example.)++"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"+"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"+"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"++# amazon-orders.csv.rules++# skip one header line+skip 1++# name the csv fields, and assign the transaction's date, amount and code.+# Avoided the "status" and "amount" hledger field names to prevent confusion.+fields date, _, toorfrom, name, amzstatus, amzamount, fees, code++# how to parse the date+date-format %b %-d, %Y++# combine two fields to make the description+description %toorfrom %name++# save the status as a tag+comment status:%amzstatus++# set the base account for all transactions+account1 assets:amazon+# leave amount1 blank so it can balance the other(s).+# I'm assuming amzamount excludes the fees, don't remember++# set a generic account2+account2 expenses:misc+amount2 %amzamount+# and maybe refine it further:+#include categorisation.rules++# add a third posting for fees, but only if they are non-zero.+if %fees [1-9]+ account3 expenses:fees+ amount3 %fees++$ hledger -f amazon-orders.csv print+2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed+ assets:amazon+ expenses:misc $20.00++2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed+ assets:amazon+ expenses:misc $25.00+ expenses:fees $1.00+++File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples++11.18.4 Paypal+--------------++Here’s a real-world rules file for (customised) Paypal CSV, with some+Paypal-specific rules, and a second rules file included:++"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"+"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""+"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""+"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""+"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""+"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""+"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""+"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""++# paypal-custom.csv.rules++# Tips:+# Export from Activity -> Statements -> Custom -> Activity download+# Suggested transaction type: "Balance affecting"+# Paypal's default fields in 2018 were:+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"+# This rules file assumes the following more detailed fields, configured in "Customize report fields":+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"++fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note++skip 1++date-format %-m/%-d/%Y++# ignore some paypal events+if+In Progress+Temporary Hold+Update to+ skip++# add more fields to the description+description %description_ %itemtitle++# save some other fields as tags+comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_++# convert to short currency symbols+if %currency USD+ currency $+if %currency EUR+ currency E+if %currency GBP+ currency P++# generate postings++# the first posting will be the money leaving/entering my paypal account+# (negative means leaving my account, in all amount fields)+account1 assets:online:paypal+amount1 %netamount++# the second posting will be money sent to/received from other party+# (account2 is set below)+amount2 -%grossamount++# if there's a fee, add a third posting for the money taken by paypal.+if %feeamount [1-9]+ account3 expenses:banking:paypal+ amount3 -%feeamount+ comment3 business:++# choose an account for the second posting++# override the default account names:+# if the amount is positive, it's income (a debit)+if %grossamount ^[^-]+ account2 income:unknown+# if negative, it's an expense (a credit)+if %grossamount ^-+ account2 expenses:unknown++# apply common rules for setting account2 & other tweaks+include common.rules++# apply some overrides specific to this csv++# Transfers from/to bank. These are usually marked Pending,+# which can be disregarded in this case.+if+Bank Account+Bank Deposit to PP Account+ description %type for %referencetxnid %itemtitle+ account2 assets:bank:wf:pchecking+ account1 assets:online:paypal++# Currency conversions+if Currency Conversion+ account2 equity:currency conversion++# common.rules++if+darcs+noble benefactor+ account2 revenues:foss donations:darcshub+ comment2 business:++if+Calm Radio+ account2 expenses:online:apps++if+electronic frontier foundation+Patreon+wikimedia+Advent of Code+ account2 expenses:dues++if Google+ account2 expenses:online:apps+ description google | music++$ hledger -f paypal-custom.csv print+2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed+ assets:online:paypal $-6.99 = $-6.99+ expenses:online:apps $6.99++2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $6.99 = $0.00+ assets:bank:wf:pchecking $-6.99++2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed+ assets:online:paypal $-7.00 = $-7.00+ expenses:dues $7.00++2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $7.00 = $0.00+ assets:bank:wf:pchecking $-7.00++2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed+ assets:online:paypal $-2.00 = $-2.00+ expenses:dues $2.00+ expenses:banking:paypal ; business:++2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $2.00 = $0.00+ assets:bank:wf:pchecking $-2.00++2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed+ assets:online:paypal $9.41 = $9.41+ revenues:foss donations:darcshub $-10.00 ; business:+ expenses:banking:paypal $0.59 ; business:+++File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top++12 Timeclock+************++The time logging format of timeclock.el, as read by hledger.++ hledger can read time logs in timeclock format. As with Ledger,+these are (a subset of) timeclock.el’s format, containing clock-in and+clock-out entries as in the example below. The date is a simple date.+The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are+optional. The timezone, if present, must be four digits and is ignored+(currently the time is always interpreted as a local time). Lines+beginning with ‘#’ or ‘;’ or ‘*’, and blank lines, are ignored.++i 2015/03/30 09:00:00 some:account name optional description after two spaces+o 2015/03/30 09:20:00+i 2015/03/31 22:21:45 another account+o 2015/04/01 02:00:34++ hledger treats each clock-in/clock-out pair as a transaction posting+some number of hours to an account. Or if the session spans more than+one day, it is split into several transactions, one for each day. For+the above time log, ‘hledger print’ generates these journal entries:++$ hledger -f t.timeclock print+2015-03-30 * optional description after two spaces+ (some:account name) 0.33h++2015-03-31 * 22:21-23:59+ (another account) 1.64h++2015-04-01 * 00:00-02:00+ (another account) 2.01h++ Here is a sample.timeclock to download and some queries to try:++$ hledger -f sample.timeclock balance # current time balances+$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009+$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week++ To generate time logs, ie to clock in and clock out, you could:++ • use emacs and the built-in timeclock.el, or the extended+ timeclock-x.el and perhaps the extras in ledgerutils.el++ • at the command line, use these bash aliases: ‘shell alias ti="echo+ i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o+ `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"’++ • or use the old ‘ti’ and ‘to’ scripts in the ledger 2.x repository.+ These rely on a "timeclock" executable which I think is just the+ ledger 2 executable renamed.+++File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top++13 Timedot+**********++‘timedot’ format is hledger’s human-friendly time logging format.+Compared to ‘timeclock’ format, it is++ • convenient for quick, approximate, and retroactive time logging+ • readable: you can see at a glance where time was spent.++ A timedot file contains a series of day entries, which might look+like this:++2021-08-04+hom:errands .... ....+fos:hledger:timedot .. ; docs+per:admin:finance ++ hledger reads this as three time transactions on this day, with each+dot representing a quarter-hour spent:++$ hledger -f a.timedot print # .timedot file extension activates the timedot reader+2021-08-04 *+ (hom:errands) 2.00++2021-08-04 *+ (fos:hledger:timedot) 0.50++2021-08-04 *+ (per:admin:finance) 0++ A day entry begins with a date line:++ • a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D).++ Optionally this can be followed on the same line by++ • a common *transaction description* for this day+ • a common *transaction comment* for this day, after a semicolon+ (‘;’).++ After the date line are zero or more optionally-indented time+transaction lines, consisting of:++ • an *account name* - any word or phrase, usually a hledger-style+ account name.+ • *two or more spaces* - a field separator, required if there is an+ amount (as in journal format).+ • a *timedot amount* - dots representing quarter hours, or a number+ representing hours.+ • an optional *comment* beginning with semicolon. This is ignored.++ In more detail, timedot amounts can be:++ • *dots*: zero or more period characters, each representing one+ quarter-hour. Spaces are ignored and can be used for grouping.+ Eg: ‘.... ..’++ • a *number*, representing hours. Eg: ‘1.5’++ • a *number immediately followed by a unit symbol* ‘s’, ‘m’, ‘h’,+ ‘d’, ‘w’, ‘mo’, or ‘y’, representing seconds, minutes, hours, days+ weeks, months or years. Eg ‘1.5h’ or ‘90m’. The following+ equivalencies are assumed:+ ‘60s’ = ‘1m’, ‘60m’ = ‘1h’, ‘24h’ = ‘1d’, ‘7d’ = ‘1w’, ‘30d’ =+ ‘1mo’, ‘365d’ = ‘1y’. (This unit will not be visible in the+ generated transaction amount, which is always in hours.)++ There is some added flexibility to help with keeping time log data in+the same file as your notes, todo lists, etc.:++ • Blank lines and lines beginning with ‘#’ or ‘;’ are ignored.++ • Before the first date line, lines beginning with ‘*’ are ignored.+ From the first date line onward, a sequence of ‘*’’s followed by a+ space at beginning of lines (ie, the headline prefix used by Emacs+ Org mode) is ignored. This means the time log can be kept under an+ Org headline, and date lines or time transaction lines can be Org+ headlines.++ • Lines not ending with a double-space and amount are parsed as+ transactions with zero amount. (Most hledger reports hide these by+ default; add -E to see them.)++ More examples:++# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.+2016/2/1+inc:client1 .... .... .... .... .... ....+fos:haskell .... ..+biz:research .++2016/2/2+inc:client1 .... ....+biz:research .++2016/2/3+inc:client1 4+fos:hledger 3+biz:research 1++* Time log+** 2020-01-01+*** adm:time .+*** adm:finance .++* 2020 Work Diary+** Q1+*** 2020-02-29+**** DONE+0700 yoga+**** UNPLANNED+**** BEGUN+hom:chores+ cleaning ...+ water plants+ outdoor - one full watering can+ indoor - light watering+**** TODO+adm:planning: trip+*** LATER++ Reporting:++$ hledger -f a.timedot print date:2016/2/2+2016-02-02 *+ (inc:client1) 2.00++2016-02-02 *+ (biz:research) 0.25++$ hledger -f a.timedot bal --daily --tree+Balance changes in 2016-02-01-2016-02-03:++ || 2016-02-01d 2016-02-02d 2016-02-03d +============++========================================+ biz || 0.25 0.25 1.00 + research || 0.25 0.25 1.00 + fos || 1.50 0 3.00 + haskell || 1.50 0 0 + hledger || 0 0 3.00 + inc || 6.00 2.00 4.00 + client1 || 6.00 2.00 4.00 +------------++----------------------------------------+ || 7.75 2.25 8.00 ++ Using period instead of colon as account name separator:++2016/2/4+fos.hledger.timedot 4+fos.ledger ..++$ hledger -f a.timedot --alias /\\./=: bal --tree+ 4.50 fos+ 4.00 hledger:timedot+ 0.50 ledger+--------------------+ 4.50++ A sample.timedot file.+++File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top++14 PART 3: REPORTING CONCEPTS+*****************************+++File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top++15 Time periods+***************++* Menu:++* Report start & end date::+* Smart dates::+* Report intervals::+* Date adjustment::+* Period expressions::+++File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods++15.1 Report start & end date+============================++By default, most hledger reports will show the full span of time+represented by the journal. The report start date will be the earliest+transaction or posting date, and the report end date will be the latest+transaction, posting, or market price date.++ Often you will want to see a shorter time span, such as the current+month. You can specify a start and/or end date using ‘-b/--begin’,+‘-e/--end’, ‘-p/--period’ or a ‘date:’ query (described below). All of+these accept the smart date syntax (below).++ Some notes:++ • End dates are exclusive, as in Ledger, so you should write the date+ _after_ the last day you want to see in the report.+ • As noted in reporting options: among start/end dates specified with+ _options_, the last (i.e. right-most) option takes precedence.+ • The effective report start and end dates are the intersection of+ the start/end dates from options and that from ‘date:’ queries.+ That is, ‘date:2019-01 date:2019 -p'2000 to 2030'’ yields January+ 2019, the smallest common time span.+ • In some cases a report interval will adjust start/end dates to fall+ on interval boundaries (see below).++ Examples:++‘-b begin on St. Patrick’s day 2016+2016/3/17’+‘-e 12/1’ end at the start of december 1st of the current year+ (11/30 will be the last date included)+‘-b all transactions on or after the 1st of the current month+thismonth’+‘-p all transactions in the current month+thismonth’+‘date:2016/3/17..’the above written as queries instead (‘..’ can also be+ replaced with ‘-’)+‘date:..12/1’+‘date:thismonth..’+‘date:thismonth’+++File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods++15.2 Smart dates+================++hledger’s user interfaces accept a "smart date" syntax for added+convenience. Smart dates optionally can be relative to today’s date, be+written with english words, and have less-significant parts omitted+(missing parts are inferred as 1). Some examples:++‘2004/10/1’, exact date, several separators allowed. Year+‘2004-01-01’, is 4+ digits, month is 1-12, day is 1-31+‘2004.9.1’+‘2004’ start of year+‘2004/10’ start of month+‘10/1’ month and day in current year+‘21’ day in current month+‘october, oct’ start of month in current year+‘yesterday, today, -1, 0, 1 days from today+tomorrow’+‘last/this/next -1, 0, 1 periods from the current period+day/week/month/quarter/year’+‘in n n periods from the current period+days/weeks/months/quarters/years’+‘n n periods from the current period+days/weeks/months/quarters/years+ahead’+‘n -n periods from the current period+days/weeks/months/quarters/years+ago’+‘20181201’ 8 digit YYYYMMDD with valid year month and+ day+‘201812’ 6 digit YYYYMM with valid year and month++ Some counterexamples - malformed digit sequences might give+surprising results:++‘201813’ 6 digits with an invalid month is parsed as start of+ 6-digit year+‘20181301’ 8 digits with an invalid month is parsed as start of+ 8-digit year+‘20181232’ 8 digits with an invalid day gives an error+‘201801012’ 9+ digits beginning with a valid YYYYMMDD gives an error++ "Today’s date" can be overridden with the ‘--today’ option, in case+it’s needed for testing or for recreating old reports. (Except for+periodic transaction rules, which are not affected by ‘--today’.)+++File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods++15.3 Report intervals+=====================++A report interval can be specified so that reports like register,+balance or activity become multi-period, showing each subperiod as a+separate row or column.++ The following standard intervals can be enabled with command-line+flags:++ • ‘-D/--daily’+ • ‘-W/--weekly’+ • ‘-M/--monthly’+ • ‘-Q/--quarterly’+ • ‘-Y/--yearly’++ More complex intervals can be specified using ‘-p/--period’,+described below.+++File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods++15.4 Date adjustment+====================++With a report interval (other than daily), report start / end dates+which have not been specified explicitly and in full (eg not ‘-b+2023-01-01’, but ‘-b 2023-01’ or ‘-b 2023’ or unspecified) are+considered flexible:++ • A flexible start date will be automatically adjusted earlier if+ needed to fall on a natural interval boundary.+ • Similarly, a flexible end date will be adjusted later if needed to+ make the last period a whole interval (the same length as the+ others).++ This is convenient for producing clean periodic reports (this is+traditional hledger behaviour). By contrast, fully-specified exact+dates will not be adjusted (this is new in hledger 1.29).++ An example: with a journal whose first date is 2023-01-10 and last+date is 2023-03-20:++ • ‘hledger bal -M -b 2023/1/15 -e 2023/3/10’+ The report periods will begin on the 15th day of each month,+ starting from 2023-01-15, and the last period’s last day will be+ 2023-03-09. (Exact start and end dates, neither is adjusted.)++ • ‘hledger bal -M -b 2023-01 -e 2023-04’ or ‘hledger bal -M’+ The report periods will begin on the 1st of each month, starting+ from 2023-01-01, and the last period’s last day will be 2023-03-31.+ (Flexible start and end dates, both are adjusted.)+++File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods++15.5 Period expressions+=======================++The ‘-p/--period’ option specifies a period expression, which is a+compact way of expressing a start date, end date, and/or report+interval.++ Here’s a period expression with a start and end date (specifying the+first quarter of 2009):++‘-p "from 2009/1/1 to 2009/4/1"’++ Several keywords like "from" and "to" are supported for readability;+these are optional. "to" can also be written as ".." or "-". The+spaces are also optional, as long as you don’t run two dates together.+So the following are equivalent to the above:++‘-p "2009/1/1 2009/4/1"’+‘-p2009/1/1to2009/4/1’+‘-p2009/1/1..2009/4/1’++ Dates are smart dates, so if the current year is 2009, these are also+equivalent to the above:++‘-p "1/1 4/1"’+‘-p "jan-apr"’+‘-p "this year to 4/1"’++ If you specify only one date, the missing start or end date will be+the earliest or latest transaction date in the journal:++‘-p "from 2009/1/1"’ everything after january 1, 2009+‘-p "since 2009/1"’ the same, since is a synonym+‘-p "from 2009"’ the same+‘-p "to 2009"’ everything before january 1, 2009++ You can also specify a period by writing a single partial or full+date:++‘-p "2009"’ the year 2009; equivalent to “2009/1/1 to 2010/1/1”+‘-p "2009/1"’ the month of january 2009; equivalent to “2009/1/1 to+ 2009/2/1”+‘-p the first day of 2009; equivalent to “2009/1/1 to+"2009/1/1"’ 2009/1/2”++ or by using the "Q" quarter-year syntax (case insensitive):++‘-p "2009Q1"’ first quarter of 2009, equivalent to “2009/1/1 to+ 2009/4/1”+‘-p "q4"’ fourth quarter of the current year++* Menu:++* Period expressions with a report interval::+* More complex report intervals::+* Multiple weekday intervals::+++File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions++15.5.1 Period expressions with a report interval+------------------------------------------------++A period expression can also begin with a report interval, separated+from the start/end dates (if any) by a space or the word ‘in’:++‘-p "weekly from 2009/1/1 to 2009/4/1"’+‘-p "monthly in 2008"’+‘-p "quarterly"’+++File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions++15.5.2 More complex report intervals+------------------------------------++Some more complex intervals can be specified within period expressions,+such as:++ • ‘biweekly’ (every two weeks)+ • ‘fortnightly’+ • ‘bimonthly’ (every two months)+ • ‘every day|week|month|quarter|year’+ • ‘every N days|weeks|months|quarters|years’++ Weekly on a custom day:++ • ‘every Nth day of week’ (‘th’, ‘nd’, ‘rd’, or ‘st’ are all accepted+ after the number)+ • ‘every WEEKDAYNAME’ (full or three-letter english weekday name,+ case insensitive)++ Monthly on a custom day:++ • ‘every Nth day [of month]’+ • ‘every Nth WEEKDAYNAME [of month]’++ Yearly on a custom day:++ • ‘every MM/DD [of year]’ (month number and day of month number)+ • ‘every MONTHNAME DDth [of year]’ (full or three-letter english+ month name, case insensitive, and day of month number)+ • ‘every DDth MONTHNAME [of year]’ (equivalent to the above)++ Examples:++‘-p "bimonthly from+2008"’+‘-p "every 2 weeks"’+‘-p "every 5 months from+2009/03"’+‘-p "every 2nd day of periods will go from Tue to Tue+week"’+‘-p "every Tue"’ same+‘-p "every 15th day"’ period boundaries will be on 15th of each+ month+‘-p "every 2nd Monday"’ period boundaries will be on second Monday+ of each month+‘-p "every 11/05"’ yearly periods with boundaries on 5th of+ November+‘-p "every 5th November"’ same+‘-p "every Nov 5th"’ same++ Show historical balances at end of the 15th day of each month (N is+an end date, exclusive as always):++$ hledger balance -H -p "every 16th day"++ Group postings from the start of wednesday to end of the following+tuesday (N is both (inclusive) start date and (exclusive) end date):++$ hledger register checking -p "every 3rd day of week"+++File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions++15.5.3 Multiple weekday intervals+---------------------------------++This special form is also supported:++ • ‘every WEEKDAYNAME,WEEKDAYNAME,...’ (full or three-letter english+ weekday names, case insensitive)++ Also, ‘weekday’ and ‘weekendday’ are shorthand for+‘mon,tue,wed,thu,fri’ and ‘sat,sun’.++ This is mainly intended for use with ‘--forecast’, to generate+periodic transactions on arbitrary days of the week. It may be less+useful with ‘-p’, since it divides each week into subperiods of unequal+length, which is unusual. (Related: #1632)++ Examples:++‘-p "every dates will be Mon, Wed, Fri; periods will be+mon,wed,fri"’ Mon-Tue, Wed-Thu, Fri-Sun+‘-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will+weekday"’ be Mon, Tue, Wed, Thu, Fri-Sun+‘-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri+weekendday"’+++File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top++16 Depth+********++With the ‘--depth NUM’ option (short form: ‘-NUM’), reports will show+accounts only to the specified depth, hiding deeper subaccounts. Use+this when you want a summary with less detail. This flag has the same+effect as a ‘depth:’ query argument: ‘depth:2’, ‘--depth=2’ or ‘-2’ are+equivalent.+++File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top++17 Queries+**********++One of hledger’s strengths is being able to quickly report on a precise+subset of your data. Most hledger commands accept optional query+arguments to restrict their scope. The syntax is as follows:++ • Zero or more space-separated query terms. These are most often+ account name substrings:++ ‘utilities food:groceries’++ • Terms with spaces or other special characters should be enclosed in+ quotes:++ ‘"personal care"’++ • Regular expressions are also supported:++ ‘"^expenses\b" "accounts (payable|receivable)"’++ • Add a query type prefix to match other parts of the data:++ ‘date:202012- desc:amazon cur:USD amt:">100" status:’++ • Add a ‘not:’ prefix to negate a term:++ ‘not:cur:USD’++* Menu:++* Query types::+* Combining query terms::+* Queries and command options::+* Queries and valuation::+* Querying with account aliases::+* Querying with cost or value::+++File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries++17.1 Query types+================++Here are the types of query term available. Remember these can also be+prefixed with *‘not:’* to convert them into a negative match.++ *‘acct:REGEX’, ‘REGEX’*+Match account names containing this (case insensitive) regular+expression. This is the default query type when there is no prefix, and+regular expression syntax is typically not needed, so usually we just+write an account name substring, like ‘expenses’ or ‘food’.++ *‘amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N’*+Match postings with a single-commodity amount equal to, less than, or+greater than N. (Postings with multi-commodity amounts are not tested+and will always match.) The comparison has two modes: if N is preceded+by a + or - sign (or is 0), the two signed numbers are compared.+Otherwise, the absolute magnitudes are compared, ignoring sign.++ *‘code:REGEX’*+Match by transaction code (eg check number).++ *‘cur:REGEX’*+Match postings or transactions including any amounts whose+currency/commodity symbol is fully matched by REGEX. (For a partial+match, use ‘.*REGEX.*’). Note, to match special characters which are+regex-significant, you need to escape them with ‘\’. And for characters+which are significant to your shell you may need one more level of+escaping. So eg to match the dollar sign:+‘hledger print cur:\\$’.++ *‘desc:REGEX’*+Match transaction descriptions.++ *‘date:PERIODEXPR’*+Match dates (or with the ‘--date2’ flag, secondary dates) within the+specified period. PERIODEXPR is a period expression with no report+interval. Examples:+‘date:2016’, ‘date:thismonth’, ‘date:2/1-2/15’,+‘date:2021-07-27..nextquarter’.++ *‘date2:PERIODEXPR’*+Match secondary dates within the specified period (independent of the+‘--date2’ flag).++ *‘depth:N’*+Match (or display, depending on command) accounts at or above this+depth.++ *‘note:REGEX’*+Match transaction notes (the part of the description right of ‘|’, or+the whole description if there’s no ‘|’).++ *‘payee:REGEX’*+Match transaction payee/payer names (the part of the description left of+‘|’, or the whole description if there’s no ‘|’).++ *‘real:, real:0’*+Match real or virtual postings respectively.++ *‘status:, status:!, status:*’*+Match unmarked, pending, or cleared transactions respectively.++ *‘type:TYPECODES’*+Match by account type (see Declaring accounts > Account types).+‘TYPECODES’ is one or more of the single-letter account type codes+‘ALERXCV’, case insensitive. Note ‘type:A’ and ‘type:E’ will also match+their respective subtypes ‘C’ (Cash) and ‘V’ (Conversion). Certain+kinds of account alias can disrupt account types, see Rewriting accounts+> Aliases and account types.++ *‘tag:REGEX[=REGEX]’*+Match by tag name, and optionally also by tag value. (To match only by+value, use ‘tag:.=REGEX’.)++ When querying by tag, note that:++ • Accounts also inherit the tags of their parent accounts+ • Postings also inherit the tags of their account and their+ transaction+ • Transactions also acquire the tags of their postings.++ (*‘inacct:ACCTNAME’*+A special query term used automatically in hledger-web only: tells+hledger-web to show the transaction register for an account.)+++File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries++17.2 Combining query terms+==========================++When given multiple query terms, most commands select things which+match:++ • any of the description terms AND+ • any of the account terms AND+ • any of the status terms AND+ • all the other terms.++ The print command is a little different, showing transactions which:++ • match any of the description terms AND+ • have any postings matching any of the positive account terms AND+ • have no postings matching any of the negative account terms AND+ • match all the other terms.++ Although these fixed rules are enough for many needs, we do not+support full boolean expressions (#203), (and you should not write AND+or OR in your queries). This makes certain queries hard to express, but+here are some tricks that can help:++ 1. Use a doubled ‘not:’ prefix. Eg, to print only the food expenses+ paid with cash:++ $ hledger print food not:not:cash++ 2. Or pre-filter the transactions with ‘print’, piping the result into+ a second hledger command (with balance assertions disabled):++ $ hledger print cash | hledger -f- -I balance food+++File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries++17.3 Queries and command options+================================++Some queries can also be expressed as command-line options: ‘depth:2’ is+equivalent to ‘--depth 2’, ‘date:2020’ is equivalent to ‘-p 2020’, etc.+When you mix command options and query arguments, generally the+resulting query is their intersection.+++File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries++17.4 Queries and valuation+==========================++When amounts are converted to other commodities in cost or value+reports, ‘cur:’ and ‘amt:’ match the old commodity symbol and the old+amount quantity, not the new ones (except in hledger 1.22.0 where it’s+reversed, see #1625).+++File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries++17.5 Querying with account aliases+==================================++When account names are rewritten with ‘--alias’ or ‘alias’, note that+‘acct:’ will match either the old or the new account name.+++File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries++17.6 Querying with cost or value+================================++When amounts are converted to other commodities in cost or value+reports, note that ‘cur:’ matches the new commodity symbol, and not the+old one, and ‘amt:’ matches the new quantity, and not the old one.+Note: this changed in hledger 1.22, previously it was the reverse, see+the discussion at #1625.+++File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top++18 Pivoting+***********++Normally, hledger groups and sums amounts within each account. The+‘--pivot FIELD’ option substitutes some other transaction field for+account names, causing amounts to be grouped and summed by that field’s+value instead. FIELD can be any of the transaction fields ‘status’,+‘code’, ‘description’, ‘payee’, ‘note’, or a tag name. When pivoting on+a tag and a posting has multiple values of that tag, only the first+value is displayed. Values containing ‘colon:separated:parts’ will be+displayed hierarchically, like account names.++ Some examples:++2016/02/16 Yearly Dues Payment+ assets:bank account 2 EUR+ income:dues -2 EUR ; member: John Doe++ Normal balance report showing account names:++$ hledger balance+ 2 EUR assets:bank account+ -2 EUR income:dues+--------------------+ 0++ Pivoted balance report, using member: tag values instead:++$ hledger balance --pivot member+ 2 EUR+ -2 EUR John Doe+--------------------+ 0++ One way to show only amounts with a member: value (using a query):++$ hledger balance --pivot member tag:member=.+ -2 EUR John Doe+--------------------+ -2 EUR++ Another way (the acct: query matches against the pivoted "account+name"):++$ hledger balance --pivot member acct:.+ -2 EUR John Doe+--------------------+ -2 EUR+++File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top++19 Generating data+******************++Two features for generating transient data (visible only at report time)+are built in to hledger’s journal format:++ • Auto posting rules can generate extra postings on certain+ transactions. They are activated by the ‘--auto’ flag.++ • Periodic transaction rules can generate repeating transactions,+ usually dated in the future, to help with forecasting or budgeting.+ They are activated by the ‘--forecast’ or ‘balance --budget’+ options, described next.+++File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top++20 Forecasting+**************++The ‘--forecast’ flag activates any periodic transaction rules in the+journal. These will generate temporary additional transactions, usually+recurring and in the future, which will appear in all reports. ‘hledger+print --forecast’ is a good way to see them.++ This can be useful for estimating balances into the future, perhaps+experimenting with different scenarios.++ It could also be useful for scripted data entry: you could describe+recurring transactions, and every so often copy the output of ‘print+--forecast’ into the journal.++ The generated transactions will have an extra tag, like+‘generated-transaction:~ PERIODICEXPR’, indicating which periodic rule+generated them. There is also a similar, hidden tag, named+‘_generated-transaction:’, which you can use to reliably match+transactions generated "just now" (rather than ‘print’ed in the past).++ The forecast transactions are generated within a _forecast period_,+which is independent of the report period. (Forecast period sets the+bounds for generated transactions, report period controls which+transactions are reported.) The forecast period begins on:++ • the start date provided within ‘--forecast’’s argument, if any+ • otherwise, the later of+ • the report start date, if specified (with ‘-b’/‘-p’/‘date:’)+ • the day after the latest ordinary transaction in the journal,+ if any++ • otherwise today.++ It ends on:++ • the end date provided within ‘--forecast’’s argument, if any+ • otherwise, the report end date, if specified (with+ ‘-e’/‘-p’/‘date:’)+ • otherwise 180 days (6 months) from today.++ Note, this means that ordinary transactions will suppress periodic+transactions, by default; the periodic transactions will not start until+after the last ordinary transaction. This is usually convenient, but+you can get around it in two ways:++ • If you need to record some transactions in the future, make them+ periodic transactions (with a single occurrence, eg: ‘~+ YYYY-MM-DD’) rather than ordinary transactions. That way they+ won’t suppress other periodic transactions.++ • Or give ‘--forecast’ a period expression argument. A forecast+ period specified this way can overlap ordinary transactions, and+ need not be in the future. Some things to note:++ • You must use ‘=’ between flag and argument; a space won’t+ work.+ • The period expression can specify the forecast period’s start+ date, end date, or both. See also Report start & end date.+ • The period expression should not specify a report interval.+ (Each periodic transaction rule specifies its own interval.)++ Some examples: ‘--forecast=202001-202004’, ‘--forecast=jan-’,+‘--forecast=2021’.+++File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top++21 Budgeting+************++With the balance command’s ‘--budget’ report, each periodic transaction+rule generates recurring budget goals in specified accounts, and goals+and actual performance can be compared. See the balance command’s doc+below.++ See also: Budgeting and Forecasting.+++File: hledger.info, Node: Cost reporting, Next: Valuation, Prev: Budgeting, Up: Top++22 Cost reporting+*****************++This section is about recording the cost of things, in transactions+where one commodity is exchanged for another. Eg an exchange of+currency, or a stock purchase or sale. First, a quick glossary:++ • Conversion - an exchange of one currency or commodity for another.+ Eg a foreign currency exchange, or a purchase or sale of stock or+ cryptocurrency.++ • Conversion transaction - a transaction involving one or more+ conversions.++ • Conversion rate - the cost per unit of one commodity in the other,+ ie the exchange rate.++ • Cost - how much of one commodity was paid to acquire the other.+ And more generally, in hledger docs: the amount exchanged in the+ "secondary" commodity (usually your base currency), whether in a+ purchase or a sale, and whether expressed per unit or in total.+ Also, the "@/@@ PRICE" notation used to represent this.++* Menu:++* -B Convert to cost::+* Equity conversion postings::+* Inferring equity postings from cost::+* Inferring cost from equity postings::+* When to infer cost/equity::+* How to record conversions::+* Cost tips::+++File: hledger.info, Node: -B Convert to cost, Next: Equity conversion postings, Up: Cost reporting++22.1 -B: Convert to cost+========================++As discussed in JOURNAL > Costs, when recording a transaction you can+also record the amount’s cost in another commodity, by adding ‘@+UNITPRICE’ or ‘@@ TOTALPRICE’.++ Then you can see a report with amounts converted to cost, by adding+the ‘-B/--cost’ flag. (Mnemonic: "B" from "cost Basis", as in Ledger).+Eg:++2022-01-01+ assets:dollars $-135 ; 135 dollars is exchanged for..+ assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each++$ hledger bal -N+ $-135 assets:dollars+ €100 assets:euros+$ hledger bal -N -B+ $-135 assets:dollars+ $135 assets:euros # <- the euros' cost++ Notes:++ -B is sensitive to the order of postings when a cost is inferred: the+inferred price will be in the commodity of the last amount. So if+example 3’s postings are reversed, while the transaction is equivalent,+-B shows something different:++2022-01-01+ assets:dollars $-135 ; 135 dollars sold+ assets:euros €100 ; for 100 euros++$ hledger bal -N -B+ €-100 assets:dollars # <- the dollars' selling price+ €100 assets:euros++ The @/@@ cost notation is convenient, but has some drawbacks: it does+not truly balance the transaction, so it disrupts the accounting+equation and tends to causes a non-zero total in balance reports.+++File: hledger.info, Node: Equity conversion postings, Next: Inferring equity postings from cost, Prev: -B Convert to cost, Up: Cost reporting++22.2 Equity conversion postings+===============================++By contrast, conventional double entry bookkeeping (DEB) uses a+different notation: an extra pair of equity postings to balance+conversion transactions. In this style, the above entry might be+written:++2022-01-01 one hundred euros purchased at $1.35 each+ assets:dollars $-135+ equity:conversion $135+ equity:conversion €-100+ assets:euros €100++ This style is more correct, but it’s also more verbose and makes cost+reporting more difficult for PTA tools.++ Happily, current hledger can read either notation, or convert one to+the other when needed, so you can use the one you prefer.++ You can even use cost notation and equivalent conversion postings at+the same time, for clarity. hledger will ignore the redundancy. But be+sure the cost and conversion posting amounts match, or you’ll see a+not-so-clear transaction balancing error message.+++File: hledger.info, Node: Inferring equity postings from cost, Next: Inferring cost from equity postings, Prev: Equity conversion postings, Up: Cost reporting++22.3 Inferring equity postings from cost+========================================++With ‘--infer-equity’, hledger detects transactions written with PTA+cost notation and adds equity conversion postings to them:++2022-01-01+ assets:dollars -$135+ assets:euros €100 @ $1.35++$ hledger print --infer-equity+2022-01-01+ assets:dollars $-135+ assets:euros €100 @ $1.35+ equity:conversion:$-€:€ €-100 ; generated-posting:+ equity:conversion:$-€:$ $135.00 ; generated-posting:++ The conversion account names can be changed with the conversion+account type declaration.++ –infer-equity is useful when when transactions have been recorded+using cost notation, to help preserve the accounting equation and+balance reports’ zero total, or to produce more conventional journal+entries for sharing with non-PTA-users.+++File: hledger.info, Node: Inferring cost from equity postings, Next: When to infer cost/equity, Prev: Inferring equity postings from cost, Up: Cost reporting++22.4 Inferring cost from equity postings+========================================++The reverse operation is possible using ‘--infer-costs’, which detects+transactions written with equity conversion postings and adds cost+notation to them:++2022-01-01+ assets:dollars $-135+ equity:conversion $135+ equity:conversion €-100+ assets:euros €100++$ hledger print --infer-costs+2022-01-01+ assets:dollars $-135 @@ €100+ equity:conversion $135+ equity:conversion €-100+ assets:euros €100++ –infer-costs is useful when combined with -B/–cost, allowing cost+reporting even when transactions have been recorded using equity+postings:++$ hledger print --infer-costs -B+2009-01-01+ assets:dollars €-100+ assets:euros €100++ Notes:++ For ‘--infer-costs’ to work, an exchange must consist of four+postings:++ 1. two non-equity postings+ 2. two equity postings, next to one another+ 3. the equity accounts must be declared, with account type+ ‘V’/‘Conversion’ (or if they are not declared, they must be named+ ‘equity:conversion’, ‘equity:trade’, ‘equity:trading’ or+ subaccounts of these)+ 4. the equity postings’ amounts must exactly match the non-equity+ postings’ amounts.++ Multiple such exchanges can coexist within a single transaction.++ When inferring cost, the order of postings matters: the cost is added+to the first of the non-equity postings involved in the exchange, in the+commodity of the last non-equity posting involved in the exchange. If+you don’t want to write your postings in the required order, you can use+explicit cost notation instead.++ –infer-equity and –infer-costs can be used together, if you have a+mixture of both notations in your journal.+++File: hledger.info, Node: When to infer cost/equity, Next: How to record conversions, Prev: Inferring cost from equity postings, Up: Cost reporting++22.5 When to infer cost/equity+==============================++Inferring equity postings or costs is still fairly new, so not enabled+by default. We’re not sure yet if that should change. Here are two+suggestions to try, experience reports welcome:++ 1. When you use -B, always use –infer-costs as well. Eg: ‘hledger bal+ -B --infer-costs’++ 2. Always run hledger with both flags enabled. Eg: ‘alias hl="hledger+ --infer-equity --infer-costs"’+++File: hledger.info, Node: How to record conversions, Next: Cost tips, Prev: When to infer cost/equity, Up: Cost reporting++22.6 How to record conversions+==============================++Essentially there are four ways to record a conversion transaction in+hledger. Here are all of them, with pros and cons.++* Menu:++* Conversion with implicit cost::+* Conversion with explicit cost::+* Conversion with equity postings::+* Conversion with equity postings and explicit cost::+++File: hledger.info, Node: Conversion with implicit cost, Next: Conversion with explicit cost, Up: How to record conversions++22.6.1 Conversion with implicit cost+------------------------------------++Let’s assume 100 EUR is converted to 120 USD. You can just record the+outflow (100 EUR) and inflow (120 USD) in the appropriate asset account:++2021-01-01+ assets:cash -100 EUR+ assets:cash 120 USD++ hledger will assume this transaction is balanced, inferring that the+conversion rate must be 1 EUR = 1.20 USD. You can see the inferred rate+by using ‘hledger print -x’.++ Pro:++ • Concise, easy++ Con:++ • Less error checking - typos in amounts or commodity symbols may not+ be detected+ • Conversion rate is not clear+ • Disturbs the accounting equation, unless you add the –infer-equity+ flag++ You can prevent accidental implicit conversions due to a mistyped+commodity symbol, by using ‘hledger check commodities’.++ You can prevent implicit conversions entirely, by using ‘hledger+check balancednoautoconversion’, or ‘-s/--strict’.+++File: hledger.info, Node: Conversion with explicit cost, Next: Conversion with equity postings, Prev: Conversion with implicit cost, Up: How to record conversions++22.6.2 Conversion with explicit cost+------------------------------------++You can add the conversion rate using @ notation:++2021-01-01+ assets:cash -100 EUR @ 1.20 USD+ assets:cash 120 USD++ Now hledger will check that 100 * 1.20 = 120, and would report an+error otherwise.++ Pro:++ • Still concise+ • Makes the conversion rate clear+ • Provides more error checking++ Con:++ • Disturbs the accounting equation, unless you add the –infer-equity+ flag+++File: hledger.info, Node: Conversion with equity postings, Next: Conversion with equity postings and explicit cost, Prev: Conversion with explicit cost, Up: How to record conversions++22.6.3 Conversion with equity postings+--------------------------------------++In strict double entry bookkeeping, the above transaction is not+balanced in EUR or in USD, since some EUR disappears, and some USD+appears. This violates the accounting equation (A+L+E=0), and prevents+reports like ‘balancesheetequity’ from showing a zero total.++ The proper way to make it balance is to add a balancing posting for+each commodity, using an equity account:++2021-01-01+ assets:cash -100 EUR+ equity:conversion 100 EUR+ equity:conversion -120 USD+ assets:cash 120 USD++ Pro:++ • Preserves the accounting equation+ • Keeps track of conversions and related gains/losses in one place+ • Standard, works in any double entry accounting system++ Con:++ • More verbose+ • Conversion rate is not obvious+ • Cost reporting requires adding the –infer-costs flag+++File: hledger.info, Node: Conversion with equity postings and explicit cost, Prev: Conversion with equity postings, Up: How to record conversions++22.6.4 Conversion with equity postings and explicit cost+--------------------------------------------------------++Here both equity postings and @ notation are used together.++2021-01-01+ assets:cash -100 EUR @ 1.20 USD+ equity:conversion 100 EUR+ equity:conversion -120 USD+ assets:cash 120 USD++ Pro:++ • Preserves the accounting equation+ • Keeps track of conversions and related gains/losses in one place+ • Makes the conversion rate clear+ • Provides more error checking++ Con:++ • Most verbose+ • Not compatible with ledger+++File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cost reporting++22.7 Cost tips+==============++ • Recording the cost/conversion rate explicitly is good because it+ makes that clear and helps detect errors.+ • Recording equity postings is good because it is correct bookkeeping+ and preserves the accounting equation.+ • Combining these is possible.+ • When you want to see the cost (or sale proceeds) of things, use+ ‘-B’ (short form of ‘--cost’).+ • If you use conversion postings without cost notation, add+ ‘--infer-costs’ also.+ • If you use cost notation without conversion postings, and you want+ to see a balanced balance sheet or print correct journal entries,+ use ‘--infer-equity’.+ • Conversion to cost is performed before valuation (described next).+++File: hledger.info, Node: Valuation, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top++23 Valuation+************++Instead of reporting amounts in their original commodity, hledger can+convert them to cost/sale amount (using the conversion rate recorded in+the transaction), and/or to market value (using some market price on a+certain date). This is controlled by the ‘--value=TYPE[,COMMODITY]’+option, which will be described below. We also provide the simpler ‘-V’+and ‘-X COMMODITY’ options, and often one of these is all you need:++* Menu:++* -V Value::+* -X Value in specified commodity::+* Valuation date::+* Finding market price::+* --infer-market-prices market prices from transactions::+* Valuation commodity::+* Simple valuation examples::+* --value Flexible valuation::+* More valuation examples::+* Interaction of valuation and queries::+* Effect of valuation on reports::+++File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Valuation++23.1 -V: Value+==============++The ‘-V/--market’ flag converts amounts to market value in their default+_valuation commodity_, using the market prices in effect on the+_valuation date(s)_, if any. More on these in a minute.+++File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation++23.2 -X: Value in specified commodity+=====================================++The ‘-X/--exchange=COMM’ option is like ‘-V’, except you tell it which+currency you want to convert to, and it tries to convert everything to+that.+++File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Valuation++23.3 Valuation date+===================++Since market prices can change from day to day, market value reports+have a valuation date (or more than one), which determines which market+prices will be used.++ For single period reports, if an explicit report end date is+specified, that will be used as the valuation date; otherwise the+valuation date is the journal’s end date.++ For multiperiod reports, each column/period is valued on the last day+of the period, by default.+++File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Valuation++23.4 Finding market price+=========================++To convert a commodity A to its market value in another commodity B,+hledger looks for a suitable market price (exchange rate) as follows, in+this order of preference :++ 1. A _declared market price_ or _inferred market price_: A’s latest+ market price in B on or before the valuation date as declared by a+ P directive, or (with the ‘--infer-market-prices’ flag) inferred+ from costs.++ 2. A _reverse market price_: the inverse of a declared or inferred+ market price from B to A.++ 3. A _forward chain of market prices_: a synthetic price formed by+ combining the shortest chain of "forward" (only 1 above) market+ prices, leading from A to B.++ 4. _Any chain of market prices_: a chain of any market prices,+ including both forward and reverse prices (1 and 2 above), leading+ from A to B.++ There is a limit to the length of these price chains; if hledger+reaches that length without finding a complete chain or exhausting all+possibilities, it will give up (with a "gave up" message visible in+‘--debug=2’ output). That limit is currently 1000.++ Amounts for which no suitable market price can be found, are not+converted.+++File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Valuation++23.5 –infer-market-prices: market prices from transactions+==========================================================++Normally, market value in hledger is fully controlled by, and requires,+P directives in your journal. Since adding and updating those can be a+chore, and since transactions usually take place at close to market+value, why not use the recorded costs as additional market prices (as+Ledger does) ? Adding the ‘--infer-market-prices’ flag to ‘-V’, ‘-X’ or+‘--value’ enables this.++ So for example, ‘hledger bs -V --infer-market-prices’ will get market+prices both from P directives and from transactions. If both occur on+the same day, the P directive takes precedence.++ There is a downside: value reports can sometimes be affected in+confusing/undesired ways by your journal entries. If this happens to+you, read all of this Valuation section carefully, and try adding+‘--debug’ or ‘--debug=2’ to troubleshoot.++ ‘--infer-market-prices’ can infer market prices from:++ • multicommodity transactions with explicit prices (‘@’/‘@@’)++ • multicommodity transactions with implicit prices (no ‘@’, two+ commodities, unbalanced). (With these, the order of postings+ matters. ‘hledger print -x’ can be useful for troubleshooting.)++ • multicommodity transactions with equity postings, if cost is+ inferred with ‘--infer-costs’.++ There is a limitation (bug) currently: when a valuation commodity is+not specified, prices inferred with ‘--infer-market-prices’ do not help+select a default valuation commodity, as ‘P’ prices would. So+conversion might not happen because no valuation commodity was detected+(‘--debug=2’ will show this). To be safe, specify the valuation+commmodity, eg:++ • ‘-X EUR --infer-market-prices’, not ‘-V --infer-market-prices’+ • ‘--value=then,EUR --infer-market-prices’, not ‘--value=then+ --infer-market-prices’++ Signed costs and market prices can be confusing. For reference, here+is the current behaviour, since hledger 1.25. (If you think it should+work differently, see #1870.)++2022-01-01 Positive Unit prices+ a A 1+ b B -1 @ A 1++2022-01-01 Positive Total prices+ a A 1+ b B -1 @@ A 1+++2022-01-02 Negative unit prices+ a A 1+ b B 1 @ A -1++2022-01-02 Negative total prices+ a A 1+ b B 1 @@ A -1+++2022-01-03 Double Negative unit prices+ a A -1+ b B -1 @ A -1++2022-01-03 Double Negative total prices+ a A -1+ b B -1 @@ A -1++ All of the transactions above are considered balanced (and on each+day, the two transactions are considered equivalent). Here are the+market prices inferred for B:++$ hledger -f- --infer-market-prices prices+P 2022-01-01 B A 1+P 2022-01-01 B A 1.0+P 2022-01-02 B A -1+P 2022-01-02 B A -1.0+P 2022-01-03 B A -1+P 2022-01-03 B A -1.0+++File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Valuation++23.6 Valuation commodity+========================++*When you specify a valuation commodity (‘-X COMM’ or ‘--value+TYPE,COMM’):*+hledger will convert all amounts to COMM, wherever it can find a+suitable market price (including by reversing or chaining prices).++ *When you leave the valuation commodity unspecified (‘-V’ or ‘--value+TYPE’):*+For each commodity A, hledger picks a default valuation commodity as+follows, in this order of preference:++ 1. The price commodity from the latest P-declared market price for A+ on or before valuation date.++ 2. The price commodity from the latest P-declared market price for A+ on any date. (Allows conversion to proceed when there are inferred+ prices before the valuation date.)++ 3. If there are no P directives at all (any commodity or date) and the+ ‘--infer-market-prices’ flag is used: the price commodity from the+ latest transaction-inferred price for A on or before valuation+ date.++ This means:++ • If you have P directives, they determine which commodities ‘-V’+ will convert, and to what.++ • If you have no P directives, and use the ‘--infer-market-prices’+ flag, costs determine it.++ Amounts for which no valuation commodity can be found are not+converted.+++File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation++23.7 Simple valuation examples+==============================++Here are some quick examples of ‘-V’:++; one euro is worth this many dollars from nov 1+P 2016/11/01 € $1.10++; purchase some euros on nov 3+2016/11/3+ assets:euros €100+ assets:checking++; the euro is worth fewer dollars by dec 21+P 2016/12/21 € $1.03++ How many euros do I have ?++$ hledger -f t.j bal -N euros+ €100 assets:euros++ What are they worth at end of nov 3 ?++$ hledger -f t.j bal -N euros -V -e 2016/11/4+ $110.00 assets:euros++ What are they worth after 2016/12/21 ? (no report end date+specified, defaults to today)++$ hledger -f t.j bal -N euros -V+ $103.00 assets:euros+++File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation++23.8 –value: Flexible valuation+===============================++‘-V’ and ‘-X’ are special cases of the more general ‘--value’ option:++ --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD.+ COMM is an optional commodity symbol.+ Shows amounts converted to:+ - default valuation commodity (or COMM) using market prices at posting dates+ - default valuation commodity (or COMM) using market prices at period end(s)+ - default valuation commodity (or COMM) using current market prices+ - default valuation commodity (or COMM) using market prices at some date++ The TYPE part selects cost or value and valuation date:++‘--value=then’++ Convert amounts to their value in the default valuation commodity,+ using market prices on each posting’s date.+‘--value=end’++ Convert amounts to their value in the default valuation commodity,+ using market prices on the last day of the report period (or if+ unspecified, the journal’s end date); or in multiperiod reports,+ market prices on the last day of each subperiod.+‘--value=now’++ Convert amounts to their value in the default valuation commodity+ using current market prices (as of when report is generated).+‘--value=YYYY-MM-DD’++ Convert amounts to their value in the default valuation commodity+ using market prices on this date.++ To select a different valuation commodity, add the optional ‘,COMM’+part: a comma, then the target commodity’s symbol. Eg:+*‘--value=now,EUR’*. hledger will do its best to convert amounts to+this commodity, deducing market prices as described above.+++File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Valuation++23.9 More valuation examples+============================++Here are some examples showing the effect of ‘--value’, as seen with+‘print’:++P 2000-01-01 A 1 B+P 2000-02-01 A 2 B+P 2000-03-01 A 3 B+P 2000-04-01 A 4 B++2000-01-01+ (a) 1 A @ 5 B++2000-02-01+ (a) 1 A @ 6 B++2000-03-01+ (a) 1 A @ 7 B++ Show the cost of each posting:++$ hledger -f- print --cost+2000-01-01+ (a) 5 B++2000-02-01+ (a) 6 B++2000-03-01+ (a) 7 B++ Show the value as of the last day of the report period (2000-02-29):++$ hledger -f- print --value=end date:2000/01-2000/03+2000-01-01+ (a) 2 B++2000-02-01+ (a) 2 B++ With no report period specified, that shows the value as of the last+day of the journal (2000-03-01):++$ hledger -f- print --value=end+2000-01-01+ (a) 3 B++2000-02-01+ (a) 3 B++2000-03-01+ (a) 3 B++ Show the current value (the 2000-04-01 price is still in effect+today):++$ hledger -f- print --value=now+2000-01-01+ (a) 4 B++2000-02-01+ (a) 4 B++2000-03-01+ (a) 4 B++ Show the value on 2000/01/15:++$ hledger -f- print --value=2000-01-15+2000-01-01+ (a) 1 B++2000-02-01+ (a) 1 B++2000-03-01+ (a) 1 B++ You may need to explicitly set a commodity’s display style, when+reverse prices are used. Eg this output might be surprising:++P 2000-01-01 A 2B++2000-01-01+ a 1B+ b++$ hledger print -x -X A+2000-01-01+ a 0+ b 0++ Explanation: because there’s no amount or commodity directive+specifying a display style for A, 0.5A gets the default style, which+shows no decimal digits. Because the displayed amount looks like zero,+the commodity symbol and minus sign are not displayed either. Adding a+commodity directive sets a more useful display style for A:++P 2000-01-01 A 2B+commodity 0.00A++2000-01-01+ a 1B+ b++$ hledger print -X A+2000-01-01+ a 0.50A+ b -0.50A+++File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation++23.10 Interaction of valuation and queries+==========================================++When matching postings based on queries in the presence of valuation,+the following happens.++ 1. The query is separated into two parts:+ 1. the currency (‘cur:’) or amount (‘amt:’).+ 2. all other parts.++ 2. The postings are matched to the currency and amount queries based+ on pre-valued amounts.+ 3. Valuation is applied to the postings.+ 4. The postings are matched to the other parts of the query based on+ post-valued amounts.++ See: 1625+++File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Valuation++23.11 Effect of valuation on reports+====================================++Here is a reference for how valuation is supposed to affect each part of+hledger’s reports (and a glossary). (It’s wide, you’ll have to scroll+sideways.) It may be useful when troubleshooting. If you find+problems, please report them, ideally with a reproducible example.+Related: #329, #1083.++Report ‘-B’, ‘-V’, ‘-X’ ‘--value=then’ ‘--value=end’‘--value=DATE’,+type ‘--cost’ ‘--value=now’+------------------------------------------------------------------------------+*print*+posting cost value at value at posting value at value+amounts report end date report or at+ or today journal DATE/today+ end+balance unchanged unchanged unchanged unchanged unchanged+assertions/assignments+*register*+starting cost value at valued at day value at value+balance report or each historical report or at+(-H) journal posting was made journal DATE/today+ end end+starting cost value at valued at day value at value+balance day before each historical day before at+(-H) report or posting was made report or DATE/today+with journal journal+report start start+interval+posting cost value at value at posting value at value+amounts report or date report or at+ journal journal DATE/today+ end end+summary summarised value at sum of postings value at value+posting cost period in interval, period at+amounts ends valued at ends DATE/today+with interval start+report+interval+running sum/average sum/average sum/average of sum/average sum/average+total/averageof of displayed values of of+ displayed displayed displayed displayed+ values values values values+*balance+(bs,+bse, cf,+is)*+balance sums of value at value at posting value at value+changes costs report end date report or at+ or today journal DATE/today+ of sums of end of of+ postings sums of sums+ postings of+ postings+budget like like like balance like like+amounts balance balance changes balances balance+(–budget) changes changes changes+grand sum of sum of sum of displayed sum of sum of+total displayed displayed valued displayed displayed+ values values values values+*balance+(bs,+bse, cf,+is) with+report+interval*+starting sums of value at sums of values value at sums+balances costs of report of postings report of+(-H) postings start of before report start of postings+ before sums of start at sums of before+ report all respective all report+ start postings posting dates postings start+ before before+ report report+ start start+balance sums of same as sums of values balance value+changes costs of –value=end of postings in change in at+(bal, postings period at each DATE/today+is, bs in period respective period, of+–change, posting dates valued at sums+cf period of+–change) ends postings+end sums of same as sums of values period end value+balances costs of –value=end of postings from balances, at+(bal -H, postings before period valued at DATE/today+is –H, from start to period period of+bs, cf) before end at ends sums+ report respective of+ start to posting dates postings+ period end+budget like like like balance like like+amounts balance balance changes/end balances balance+(–budget) changes/end changes/end balances changes/end+ balances balances balances+row sums, sums, sums, averages sums, sums,+totals, averages averages of displayed averages averages+row of of values of of+averages displayed displayed displayed displayed+(-T, -A) values values values values+column sums of sums of sums of sums of sums+totals displayed displayed displayed values displayed of+ values values values displayed+ values+grand sum, sum, sum, average of sum, sum,+total, average of average of column totals average of average+grand column column column of+average totals totals totals column+ totals++ ‘--cumulative’ is omitted to save space, it works like ‘-H’ but with+a zero starting balance.++ *Glossary:*++_cost_++ calculated using price(s) recorded in the transaction(s).+_value_++ market value using available market price declarations, or the+ unchanged amount if no conversion rate can be found.+_report start_++ the first day of the report period specified with -b or -p or+ date:, otherwise today.+_report or journal start_++ the first day of the report period specified with -b or -p or+ date:, otherwise the earliest transaction date in the journal,+ otherwise today.+_report end_++ the last day of the report period specified with -e or -p or date:,+ otherwise today.+_report or journal end_++ the last day of the report period specified with -e or -p or date:,+ otherwise the latest transaction date in the journal, otherwise+ today.+_report interval_++ a flag (-D/-W/-M/-Q/-Y) or period expression that activates the+ report’s multi-period mode (whether showing one or many+ subperiods).+++File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Valuation, Up: Top++24 PART 4: COMMANDS+*******************++* Menu:++* Commands overview::+* accounts::+* activity::+* add::+* aregister::+* balance::+* balancesheet::+* balancesheetequity::+* cashflow::+* check::+* close::+* codes::+* commodities::+* descriptions::+* diff::+* files::+* help::+* import::+* incomestatement::+* notes::+* payees::+* prices::+* print::+* register::+* rewrite::+* roi::+* stats::+* tags::+* test::+++File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS++24.1 Commands overview+======================++Here are the built-in commands:++* Menu:++* DATA ENTRY::+* DATA CREATION::+* DATA MANAGEMENT::+* REPORTS FINANCIAL::+* REPORTS VERSATILE::+* REPORTS BASIC::+* HELP::+* ADD-ONS::+++File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview++24.1.1 DATA ENTRY+-----------------++These data entry commands are the only ones which can modify your+journal file.++ • add - add transactions using terminal prompts+ • import - add new transactions from other files, eg CSV files+++File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview++24.1.2 DATA CREATION+--------------------++ • close - generate balance-zeroing/restoring transactions+ • rewrite - generate auto postings, like print –auto+++File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview++24.1.3 DATA MANAGEMENT+----------------------++ • check - check for various kinds of error in the data+ • diff - compare account transactions in two journal files+++File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview++24.1.4 REPORTS, FINANCIAL+-------------------------++ • aregister (areg) - show transactions in a particular account+ • balancesheet (bs) - show assets, liabilities and net worth+ • balancesheetequity (bse) - show assets, liabilities and equity+ • cashflow (cf) - show changes in liquid assets+ • incomestatement (is) - show revenues and expenses+++File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview++24.1.5 REPORTS, VERSATILE+-------------------------++ • balance (bal) - show balance changes, end balances, budgets,+ gains..+ • print - show transactions or export journal data+ • register (reg) - show postings in one or more accounts & running+ total+ • roi - show return on investments+++File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview++24.1.6 REPORTS, BASIC+---------------------++ • accounts - show account names+ • activity - show bar charts of posting counts per period+ • codes - show transaction codes+ • commodities - show commodity/currency symbols+ • descriptions - show transaction descriptions+ • files - show input file paths+ • notes - show note parts of transaction descriptions+ • payees - show payee parts of transaction descriptions+ • prices - show market prices+ • stats - show journal statistics+ • tags - show tag names+ • test - run self tests+++File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview++24.1.7 HELP+-----------++ • help - show the hledger manual with info/man/pager+++File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview++24.1.8 ADD-ONS+--------------++And here are some typical add-on commands. Some of these are installed+by the hledger-install script. If installed, they will appear in+hledger’s commands list:++ • ui - run hledger’s terminal UI+ • web - run hledger’s web UI+ • iadd - add transactions using a TUI (currently hard to build)+ • interest - generate interest transactions+ • stockquotes - download market prices from AlphaVantage+ • Scripts and add-ons - check-fancyassertions, edit, fifo, git, move,+ pijul, plot, and more..++ Next, each command is described in detail, in alphabetical order.+++File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS++24.2 accounts+=============++Show account names.++ This command lists account names. By default it shows all known+accounts, either used in transactions or declared with account+directives.++ With query arguments, only matched account names and account names+referenced by matched postings are shown.++ Or it can show just the used accounts (‘--used’/‘-u’), the declared+accounts (‘--declared’/‘-d’), the accounts declared but not used+(‘--unused’), the accounts used but not declared (‘--undeclared’), or+the first account matched by an account name pattern, if any (‘--find’).++ It shows a flat list by default. With ‘--tree’, it uses indentation+to show the account hierarchy. In flat mode you can add ‘--drop N’ to+omit the first few account name components. Account names can be+depth-clipped with ‘depth:N’ or ‘--depth N’ or ‘-N’.++ With ‘--types’, it also shows each account’s type, if it’s known.+(See Declaring accounts > Account types.)++ With ‘--positions’, it also shows the file and line number of each+account’s declaration, if any, and the account’s overall declaration+order; these may be useful when troubleshooting account display order.++ With ‘--directives’, it adds the ‘account’ keyword, showing valid+account directives which can be pasted into a journal file. This is+useful together with ‘--undeclared’ when updating your account+declarations to satisfy ‘hledger check accounts’.++ The ‘--find’ flag can be used to look up a single account name, in+the same way that the ‘aregister’ command does. It returns the+alphanumerically-first matched account name, or if none can be found, it+fails with a non-zero exit code.++ Examples:++$ hledger accounts+assets:bank:checking+assets:bank:saving+assets:cash+expenses:food+expenses:supplies+income:gifts+income:salary+liabilities:debts++$ hledger accounts --undeclared --directives >> $LEDGER_FILE+$ hledger check accounts+++File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS++24.3 activity+=============++Show an ascii barchart of posting counts per interval.++ The activity command displays an ascii histogram showing transaction+counts by day, week, month or other reporting interval (by day is the+default). With query arguments, it counts only matched transactions.++ Examples:++$ hledger activity --quarterly+2008-01-01 **+2008-04-01 *******+2008-07-01 +2008-10-01 **+++File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: PART 4 COMMANDS++24.4 add+========++Prompt for transactions and add them to the journal. Any arguments will+be used as default inputs for the first N prompts.++ Many hledger users edit their journals directly with a text editor,+or generate them from CSV. For more interactive data entry, there is the+‘add’ command, which prompts interactively on the console for new+transactions, and appends them to the main journal file (which should be+in journal format). Existing transactions are not changed. This is one+of the few hledger commands that writes to the journal file (see also+‘import’).++ To use it, just run ‘hledger add’ and follow the prompts. You can+add as many transactions as you like; when you are finished, enter ‘.’+or press control-d or control-c to exit.++ Features:++ • add tries to provide useful defaults, using the most similar (by+ description) recent transaction (filtered by the query, if any) as+ a template.+ • You can also set the initial defaults with command line arguments.+ • Readline-style edit keys can be used during data entry.+ • The tab key will auto-complete whenever possible - accounts,+ payees/descriptions, dates (‘yesterday’, ‘today’, ‘tomorrow’). If+ the input area is empty, it will insert the default value.+ • If the journal defines a default commodity, it will be added to any+ bare numbers entered.+ • A parenthesised transaction code may be entered following a date.+ • Comments and tags may be entered following a description or amount.+ • If you make a mistake, enter ‘<’ at any prompt to go one step+ backward.+ • Input prompts are displayed in a different colour when the terminal+ supports it.++ Example (see https://hledger.org/add.html for a detailed tutorial):++$ hledger add+Adding transactions to journal file /src/hledger/examples/sample.journal+Any command line arguments will be used as defaults.+Use tab key to complete, readline keys to edit, enter to accept defaults.+An optional (CODE) may follow transaction dates.+An optional ; COMMENT may follow descriptions or amounts.+If you make a mistake, enter < at any prompt to go one step backward.+To end a transaction, enter . when prompted.+To quit, enter . at a date prompt or press control-d or control-c.+Date [2015/05/22]: +Description: supermarket+Account 1: expenses:food+Amount 1: $10+Account 2: assets:checking+Amount 2 [$-10.0]: +Account 3 (or . or enter to finish this transaction): .+2015/05/22 supermarket+ expenses:food $10+ assets:checking $-10.0++Save this transaction to the journal ? [y]: +Saved.+Starting the next transaction (. or ctrl-D/ctrl-C to quit)+Date [2015/05/22]: <CTRL-D> $++ On Microsoft Windows, the add command makes sure that no part of the+file path ends with a period, as that would cause problems (#1056).+++File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS++24.5 aregister+==============++(areg)++ Show the transactions and running historical balance of a single+account, with each transaction displayed as one line.++ ‘aregister’ shows the overall transactions affecting a particular+account (and any subaccounts). Each report line represents one+transaction in this account. Transactions before the report start date+are always included in the running balance (‘--historical’ mode is+always on).++ This is a more "real world", bank-like view than the ‘register’+command (which shows individual postings, possibly from multiple+accounts, not necessarily in historical mode). As a quick rule of+thumb: - use ‘aregister’ for reviewing and reconciling real-world+asset/liability accounts - use ‘register’ for reviewing detailed+revenues/expenses.++ ‘aregister’ requires one argument: the account to report on. You can+write either the full account name, or a case-insensitive regular+expression which will select the alphabetically first matched account.++ When there are multiple matches, the alphabetically-first choice can+be surprising; eg if you have ‘assets:per:checking 1’ and+‘assets:biz:checking 2’ accounts, ‘hledger areg checking’ would select+‘assets:biz:checking 2’. It’s just a convenience to save typing, so if+in doubt, write the full account name, or a distinctive substring that+matches uniquely.++ Transactions involving subaccounts of this account will also be+shown. ‘aregister’ ignores depth limits, so its final total will always+match a balance report with similar arguments.++ Any additional arguments form a query which will filter the+transactions shown. Note some queries will disturb the running balance,+causing it to be different from the account’s real-world running+balance.++ An example: this shows the transactions and historical running+balance during july, in the first account whose name contains+"checking":++$ hledger areg checking date:jul++ Each ‘aregister’ line item shows:++ • the transaction’s date (or the relevant posting’s date if+ different, see below)+ • the names of all the other account(s) involved in this transaction+ (probably abbreviated)+ • the total change to this account’s balance from this transaction+ • the account’s historical running balance after this transaction.++ Transactions making a net change of zero are not shown by default;+add the ‘-E/--empty’ flag to show them.++ For performance reasons, column widths are chosen based on the first+1000 lines; this means unusually wide values in later lines can cause+visual discontinuities as column widths are adjusted. If you want to+ensure perfect alignment, at the cost of more time and memory, use the+‘--align-all’ flag.++ This command also supports the output destination and output format+options. The output formats supported are ‘txt’, ‘csv’, and ‘json’.++* Menu:++* aregister and custom posting dates::+++File: hledger.info, Node: aregister and custom posting dates, Up: aregister++24.5.1 aregister and custom posting dates+-----------------------------------------++Transactions whose date is outside the report period can still be shown,+if they have a posting to this account dated inside the report period.+(And in this case it’s the posting date that is shown.) This ensures+that ‘aregister’ can show an accurate historical running balance,+matching the one shown by ‘register -H’ with the same arguments.++ To filter strictly by transaction date instead, add the ‘--txn-dates’+flag. If you use this flag and some of your postings have custom dates,+it’s probably best to assume the running balance is wrong.+++File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS++24.6 balance+============++(bal)++ Show accounts and their balances.++ ‘balance’ is one of hledger’s oldest and most versatile commands, for+listing account balances, balance changes, values, value changes and+more, during one time period or many. Generally it shows a table, with+rows representing accounts, and columns representing periods.++ Note there are some higher-level variants of the ‘balance’ command+with convenient defaults, which can be simpler to use: ‘balancesheet’,+‘balancesheetequity’, ‘cashflow’ and ‘incomestatement’. When you need+more control, then use ‘balance’.++* Menu:++* balance features::+* Simple balance report::+* Balance report line format::+* Filtered balance report::+* List or tree mode::+* Depth limiting::+* Dropping top-level accounts::+* Showing declared accounts::+* Sorting by amount::+* Percentages::+* Multi-period balance report::+* Balance change end balance::+* Balance report types::+* Budget report::+* Data layout::+* Useful balance reports::+++File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance++24.6.1 balance features+-----------------------++Here’s a quick overview of the ‘balance’ command’s features, followed by+more detailed descriptions and examples. Many of these work with the+higher-level commands as well.++ ‘balance’ can show..++ • accounts as a list (‘-l’) or a tree (‘-t’)+ • optionally depth-limited (‘-[1-9]’)+ • sorted by declaration order and name, or by amount++ ..and their..++ • balance changes (the default)+ • or actual and planned balance changes (‘--budget’)+ • or value of balance changes (‘-V’)+ • or change of balance values (‘--valuechange’)+ • or unrealised capital gain/loss (‘--gain’)++ ..in..++ • one time period (the whole journal period by default)+ • or multiple periods (‘-D’, ‘-W’, ‘-M’, ‘-Q’, ‘-Y’, ‘-p INTERVAL’)++ ..either..++ • per period (the default)+ • or accumulated since report start date (‘--cumulative’)+ • or accumulated since account creation (‘--historical/-H’)++ ..possibly converted to..++ • cost (‘--value=cost[,COMM]’/‘--cost’/‘-B’)+ • or market value, as of transaction dates (‘--value=then[,COMM]’)+ • or at period ends (‘--value=end[,COMM]’)+ • or now (‘--value=now’)+ • or at some other date (‘--value=YYYY-MM-DD’)++ ..with..++ • totals (‘-T’), averages (‘-A’), percentages (‘-%’), inverted sign+ (‘--invert’)+ • rows and columns swapped (‘--transpose’)+ • another field used as account name (‘--pivot’)+ • custom-formatted line items (single-period reports only)+ (‘--format’)+ • commodities displayed on the same line or multiple lines+ (‘--layout’)++ This command supports the output destination and output format+options, with output formats ‘txt’, ‘csv’, ‘json’, and (multi-period+reports only:) ‘html’. In ‘txt’ output in a colour-supporting terminal,+negative amounts are shown in red.++ The ‘--related’/‘-r’ flag shows the balance of the _other_ postings+in the transactions of the postings which would normally be shown.+++File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance++24.6.2 Simple balance report+----------------------------++With no arguments, ‘balance’ shows a list of all accounts and their+change of balance - ie, the sum of posting amounts, both inflows and+outflows - during the entire period of the journal. ("Simple" here+means just one column of numbers, covering a single period. You can+also have multi-period reports, described later.)++ For real-world accounts, these numbers will normally be their end+balance at the end of the journal period; more on this below.++ Accounts are sorted by declaration order if any, and then+alphabetically by account name. For instance (using+examples/sample.journal):++$ hledger -f examples/sample.journal bal+ $1 assets:bank:saving+ $-2 assets:cash+ $1 expenses:food+ $1 expenses:supplies+ $-1 income:gifts+ $-1 income:salary+ $1 liabilities:debts+--------------------+ 0 ++ Accounts with a zero balance (and no non-zero subaccounts, in tree+mode - see below) are hidden by default. Use ‘-E/--empty’ to show them+(revealing ‘assets:bank:checking’ here):++$ hledger -f examples/sample.journal bal -E+ 0 assets:bank:checking+ $1 assets:bank:saving+ $-2 assets:cash+ $1 expenses:food+ $1 expenses:supplies+ $-1 income:gifts+ $-1 income:salary+ $1 liabilities:debts+--------------------+ 0 ++ The total of the amounts displayed is shown as the last line, unless+‘-N’/‘--no-total’ is used.+++File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance++24.6.3 Balance report line format+---------------------------------++For single-period balance reports displayed in the terminal (only), you+can use ‘--format FMT’ to customise the format and content of each line.+Eg:++$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"+ assets $-1+ bank:saving $1+ cash $-2+ expenses $2+ food $1+ supplies $1+ income $-2+ gifts $-1+ salary $-1+ liabilities:debts $1+---------------------------------+ 0++ The FMT format string specifies the formatting applied to each+account/balance pair. It may contain any suitable text, with data+fields interpolated like so:++ ‘%[MIN][.MAX](FIELDNAME)’++ • MIN pads with spaces to at least this width (optional)++ • MAX truncates at this width (optional)++ • FIELDNAME must be enclosed in parentheses, and can be one of:++ • ‘depth_spacer’ - a number of spaces equal to the account’s+ depth, or if MIN is specified, MIN * depth spaces.+ • ‘account’ - the account’s name+ • ‘total’ - the account’s balance/posted total, right justified++ Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:++ • ‘%_’ - render on multiple lines, bottom-aligned (the default)+ • ‘%^’ - render on multiple lines, top-aligned+ • ‘%,’ - render on one line, comma-separated++ There are some quirks. Eg in one-line mode, ‘%(depth_spacer)’ has no+effect, instead ‘%(account)’ has indentation built in. Experimentation+may be needed to get pleasing results.++ Some example formats:++ • ‘%(total)’ - the account’s total+ • ‘%-20.20(account)’ - the account’s name, left justified, padded to+ 20 characters and clipped at 20 characters+ • ‘%,%-50(account) %25(total)’ - account name padded to 50+ characters, total padded to 20 characters, with multiple+ commodities rendered on one line+ • ‘%20(total) %2(depth_spacer)%-(account)’ - the default format for+ the single-column balance report+++File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance++24.6.4 Filtered balance report+------------------------------++You can show fewer accounts, a different time period, totals from+cleared transactions only, etc. by using query arguments or options to+limit the postings being matched. Eg:++$ hledger -f examples/sample.journal bal --cleared assets date:200806+ $-2 assets:cash+--------------------+ $-2 +++File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance++24.6.5 List or tree mode+------------------------++By default, or with ‘-l/--flat’, accounts are shown as a flat list with+their full names visible, as in the examples above.++ With ‘-t/--tree’, the account hierarchy is shown, with subaccounts’+"leaf" names indented below their parent:++$ hledger -f examples/sample.journal balance+ $-1 assets+ $1 bank:saving+ $-2 cash+ $2 expenses+ $1 food+ $1 supplies+ $-2 income+ $-1 gifts+ $-1 salary+ $1 liabilities:debts+--------------------+ 0++ Notes:++ • "Boring" accounts are combined with their subaccount for more+ compact output, unless ‘--no-elide’ is used. Boring accounts have+ no balance of their own and just one subaccount (eg ‘assets:bank’+ and ‘liabilities’ above).++ • All balances shown are "inclusive", ie including the balances from+ all subaccounts. Note this means some repetition in the output,+ which requires explanation when sharing reports with+ non-plaintextaccounting-users. A tree mode report’s final total is+ the sum of the top-level balances shown, not of all the balances+ shown.++ • Each group of sibling accounts (ie, under a common parent) is+ sorted separately.+++File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance++24.6.6 Depth limiting+---------------------++With a ‘depth:NUM’ query, or ‘--depth NUM’ option, or just ‘-NUM’ (eg:+‘-3’) balance reports will show accounts only to the specified depth,+hiding the deeper subaccounts. This can be useful for getting an+overview without too much detail.++ Account balances at the depth limit always include the balances from+any deeper subaccounts (even in list mode). Eg, limiting to depth 1:++$ hledger -f examples/sample.journal balance -1+ $-1 assets+ $2 expenses+ $-2 income+ $1 liabilities+--------------------+ 0 +++File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance++24.6.7 Dropping top-level accounts+----------------------------------++You can also hide one or more top-level account name parts, using+‘--drop NUM’. This can be useful for hiding repetitive top-level+account names:++$ hledger -f examples/sample.journal bal expenses --drop 1+ $1 food+ $1 supplies+--------------------+ $2 +++File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance++24.6.8 Showing declared accounts+--------------------------------++With ‘--declared’, accounts which have been declared with an account+directive will be included in the balance report, even if they have no+transactions. (Since they will have a zero balance, you will also need+‘-E/--empty’ to see them.)++ More precisely, _leaf_ declared accounts (with no subaccounts) will+be included, since those are usually the more useful in reports.++ The idea of this is to be able to see a useful "complete" balance+report, even when you don’t have transactions in all of your declared+accounts yet.+++File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance++24.6.9 Sorting by amount+------------------------++With ‘-S/--sort-amount’, accounts with the largest (most positive)+balances are shown first. Eg: ‘hledger bal expenses -MAS’ shows your+biggest averaged monthly expenses first. When more than one commodity+is present, they will be sorted by the alphabetically earliest commodity+first, and then by subsequent commodities (if an amount is missing a+commodity, it is treated as 0).++ Revenues and liability balances are typically negative, however, so+‘-S’ shows these in reverse order. To work around this, you can add+‘--invert’ to flip the signs. (Or, use one of the higher-level reports,+which flip the sign automatically. Eg: ‘hledger incomestatement -MAS’).+++File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance++24.6.10 Percentages+-------------------++With ‘-%/--percent’, balance reports show each account’s value expressed+as a percentage of the (column) total.++ Note it is not useful to calculate percentages if the amounts in a+column have mixed signs. In this case, make a separate report for each+sign, eg:++$ hledger bal -% amt:`>0`+$ hledger bal -% amt:`<0`++ Similarly, if the amounts in a column have mixed commodities, convert+them to one commodity with ‘-B’, ‘-V’, ‘-X’ or ‘--value’, or make a+separate report for each commodity:++$ hledger bal -% cur:\\$+$ hledger bal -% cur:€+++File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance++24.6.11 Multi-period balance report+-----------------------------------++With a report interval (set by the ‘-D/--daily’, ‘-W/--weekly’,+‘-M/--monthly’, ‘-Q/--quarterly’, ‘-Y/--yearly’, or ‘-p/--period’ flag),+‘balance’ shows a tabular report, with columns representing successive+time periods (and a title):++$ hledger -f examples/sample.journal bal --quarterly income expenses -E+Balance changes in 2008:++ || 2008q1 2008q2 2008q3 2008q4 +===================++=================================+ expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 +-------------------++---------------------------------+ || $-1 $1 0 0 ++ Notes:++ • The report’s start/end dates will be expanded, if necessary, to+ fully encompass the displayed subperiods (so that the first and+ last subperiods have the same duration as the others).+ • Leading and trailing periods (columns) containing all zeroes are+ not shown, unless ‘-E/--empty’ is used.+ • Accounts (rows) containing all zeroes are not shown, unless+ ‘-E/--empty’ is used.+ • Amounts with many commodities are shown in abbreviated form, unless+ ‘--no-elide’ is used. _(experimental)_+ • Average and/or total columns can be added with the ‘-A/--average’+ and ‘-T/--row-total’ flags.+ • The ‘--transpose’ flag can be used to exchange rows and columns.+ • The ‘--pivot FIELD’ option causes a different transaction field to+ be used as "account name". See PIVOTING.++ Multi-period reports with many periods can be too wide for easy+viewing in the terminal. Here are some ways to handle that:++ • Hide the totals row with ‘-N/--no-total’+ • Convert to a single currency with ‘-V’+ • Maximize the terminal window+ • Reduce the terminal’s font size+ • View with a pager like less, eg: ‘hledger bal -D --color=yes | less+ -RS’+ • Output as CSV and use a CSV viewer like visidata (‘hledger bal -D+ -O csv | vd -f csv’), Emacs’ csv-mode (‘M-x csv-mode, C-c C-a’), or+ a spreadsheet (‘hledger bal -D -o a.csv && open a.csv’)+ • Output as HTML and view with a browser: ‘hledger bal -D -o a.html+ && open a.html’+++File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance++24.6.12 Balance change, end balance+-----------------------------------++It’s important to be clear on the meaning of the numbers shown in+balance reports. Here is some terminology we use:++ A *_balance change_* is the net amount added to, or removed from, an+account during some period.++ An *_end balance_* is the amount accumulated in an account as of some+date (and some time, but hledger doesn’t store that; assume end of day+in your timezone). It is the sum of previous balance changes.++ We call it a *_historical end balance_* if it includes all balance+changes since the account was created. For a real world account, this+means it will match the "historical record", eg the balances reported in+your bank statements or bank web UI. (If they are correct!)++ In general, balance changes are what you want to see when reviewing+revenues and expenses, and historical end balances are what you want to+see when reviewing or reconciling asset, liability and equity accounts.++ ‘balance’ shows balance changes by default. To see accurate+historical end balances:++ 1. Initialise account starting balances with an "opening balances"+ transaction (a transfer from equity to the account), unless the+ journal covers the account’s full lifetime.++ 2. Include all of of the account’s prior postings in the report, by+ not specifying a report start date, or by using the+ ‘-H/--historical’ flag. (‘-H’ causes report start date to be+ ignored when summing postings.)+++File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance++24.6.13 Balance report types+----------------------------++The balance command is quite flexible; here is the full detail on how to+control what it reports. If the following seems complicated, don’t+worry - this is for advanced reporting, and it does typically take some+time and experimentation to get clear on all these report modes.++ There are three important option groups:++ ‘hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]+...’++* Menu:++* Calculation type::+* Accumulation type::+* Valuation type::+* Combining balance report types::+++File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types++24.6.13.1 Calculation type+..........................++The basic calculation to perform for each table cell. It is one of:++ • ‘--sum’ : sum the posting amounts (*default*)+ • ‘--budget’ : sum the amounts, but also show the budget goal amount+ (for each account/period)+ • ‘--valuechange’ : show the change in period-end historical balance+ values (caused by deposits, withdrawals, and/or market price+ fluctuations)+ • ‘--gain’ : show the unrealised capital gain/loss, (the current+ valued balance minus each amount’s original cost)+++File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types++24.6.13.2 Accumulation type+...........................++How amounts should accumulate across report periods. Another way to say+it: which time period’s postings should contribute to each cell’s+calculation. It is one of:++ • ‘--change’ : calculate with postings from column start to column+ end, ie "just this column". Typically used to see+ revenues/expenses. (*default for balance, incomestatement*)++ • ‘--cumulative’ : calculate with postings from report start to+ column end, ie "previous columns plus this column". Typically used+ to show changes accumulated since the report’s start date. Not+ often used.++ • ‘--historical/-H’ : calculate with postings from journal start to+ column end, ie "all postings from before report start date until+ this column’s end". Typically used to see historical end balances+ of assets/liabilities/equity. (*default for balancesheet,+ balancesheetequity, cashflow*)+++File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types++24.6.13.3 Valuation type+........................++Which kind of value or cost conversion should be applied, if any, before+displaying the report. It is one of:++ • no valuation type : don’t convert to cost or value (*default*)+ • ‘--value=cost[,COMM]’ : convert amounts to cost (then optionally to+ some other commodity)+ • ‘--value=then[,COMM]’ : convert amounts to market value on+ transaction dates+ • ‘--value=end[,COMM]’ : convert amounts to market value on period+ end date(s)+ (*default with ‘--valuechange’, ‘--gain’*)+ • ‘--value=now[,COMM]’ : convert amounts to market value on today’s+ date+ • ‘--value=YYYY-MM-DD[,COMM]’ : convert amounts to market value on+ another date++ or one of the equivalent simpler flags:++ • ‘-B/--cost’ : like –value=cost (though, note –cost and –value are+ independent options which can both be used at once)+ • ‘-V/--market’ : like –value=end+ • ‘-X COMM/--exchange COMM’ : like –value=end,COMM++ See Cost reporting and Valuation for more about these.+++File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types++24.6.13.4 Combining balance report types+........................................++Most combinations of these options should produce reasonable reports,+but if you find any that seem wrong or misleading, let us know. The+following restrictions are applied:++ • ‘--valuechange’ implies ‘--value=end’+ • ‘--valuechange’ makes ‘--change’ the default when used with the+ ‘balancesheet’/‘balancesheetequity’ commands+ • ‘--cumulative’ or ‘--historical’ disables ‘--row-total/-T’++ For reference, here is what the combinations of accumulation and+valuation show:++Valuation:>no valuation ‘--value= then’ ‘--value= end’ ‘--value=+Accumulation:v YYYY-MM-DD+ /now’+-----------------------------------------------------------------------------+‘--change’change in sum of period-end DATE-value+ period posting-date value of of change in+ market values change in period+ in period period+‘--cumulative’change from sum of period-end DATE-value+ report start to posting-date value of of change+ period end market values change from from report+ from report report start start to+ start to period to period end period end+ end+‘--historicalchange from sum of period-end DATE-value+/-H’ journal start posting-date value of of change+ to period end market values change from from journal+ (historical end from journal journal start start to+ balance) start to period to period end period end+ end+++File: hledger.info, Node: Budget report, Next: Data layout, Prev: Balance report types, Up: balance++24.6.14 Budget report+---------------------++The ‘--budget’ report type activates extra columns showing any budget+goals for each account and period. The budget goals are defined by+periodic transactions. This is useful for comparing planned and actual+income, expenses, time usage, etc.++ For example, you can take average monthly expenses in the common+expense categories to construct a minimal monthly budget:++;; Budget+~ monthly+ income $2000+ expenses:food $400+ expenses:bus $50+ expenses:movies $30+ assets:bank:checking++;; Two months worth of expenses+2017-11-01+ income $1950+ expenses:food $396+ expenses:bus $49+ expenses:movies $30+ expenses:supplies $20+ assets:bank:checking++2017-12-01+ income $2100+ expenses:food $412+ expenses:bus $53+ expenses:gifts $100+ assets:bank:checking++ You can now see a monthly budget report:++$ hledger balance -M --budget+Budget performance in 2017/11/01-2017/12/31:++ || Nov Dec +======================++====================================================+ assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++----------------------------------------------------+ || 0 [ 0] 0 [ 0] ++ This is different from a normal balance report in several ways:++ • Only accounts with budget goals during the report period are shown,+ by default.++ • In each column, in square brackets after the actual amount, budget+ goal amounts are shown, and the actual/goal percentage. (Note:+ budget goals should be in the same commodity as the actual amount.)++ • All parent accounts are always shown, even in list mode. Eg+ assets, assets:bank, and expenses above.++ • Amounts always include all subaccounts, budgeted or unbudgeted,+ even in list mode.++ This means that the numbers displayed will not always add up! Eg+above, the ‘expenses’ actual amount includes the gifts and supplies+transactions, but the ‘expenses:gifts’ and ‘expenses:supplies’ accounts+are not shown, as they have no budget amounts declared.++ This can be confusing. When you need to make things clearer, use the+‘-E/--empty’ flag, which will reveal all accounts including unbudgeted+ones, giving the full picture. Eg:++$ hledger balance -M --budget --empty+Budget performance in 2017/11/01-2017/12/31:++ || Nov Dec +======================++====================================================+ assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++----------------------------------------------------+ || 0 [ 0] 0 [ 0] ++ You can roll over unspent budgets to next period with ‘--cumulative’:++$ hledger balance -M --budget --cumulative+Budget performance in 2017/11/01-2017/12/31:++ || Nov Dec +======================++====================================================+ assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] +----------------------++----------------------------------------------------+ || 0 [ 0] 0 [ 0] ++ It’s common to limit budgets/budget reports to just expenses++hledger bal -M --budget expenses++ or just revenues and expenses (eg, using account types):++hledger bal -M --budget type:rx++ It’s also common to limit or convert them to a single currency+(‘cur:COMM’ or ‘-X COMM [--infer-market-prices]’). If showing multiple+currencies, ‘--layout bare’ or ‘--layout tall’ can help.++ For more examples and notes, see Budgeting.++* Menu:++* Budget report start date::+* Budgets and subaccounts::+* Selecting budget goals::+* Budget vs forecast::+++File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report++24.6.14.1 Budget report start date+..................................++This might be a bug, but for now: when making budget reports, it’s a+good idea to explicitly set the report’s start date to the first day of+a reporting period, because a periodic rule like ‘~ monthly’ generates+its transactions on the 1st of each month, and if your journal has no+regular transactions on the 1st, the default report start date could+exclude that budget goal, which can be a little surprising. Eg here the+default report period is just the day of 2020-01-15:++~ monthly in 2020+ (expenses:food) $500++2020-01-15+ expenses:food $400+ assets:checking++$ hledger bal expenses --budget+Budget performance in 2020-01-15:++ || 2020-01-15 +==============++============+ <unbudgeted> || $400 +--------------++------------+ || $400 ++ To avoid this, specify the budget report’s period, or at least the+start date, with ‘-b’/‘-e’/‘-p’/‘date:’, to ensure it includes the+budget goal transactions (periodic transactions) that you want. Eg,+adding ‘-b 2020/1/1’ to the above:++$ hledger bal expenses --budget -b 2020/1/1+Budget performance in 2020-01-01..2020-01-15:++ || 2020-01-01..2020-01-15 +===============++========================+ expenses:food || $400 [80% of $500] +---------------++------------------------+ || $400 [80% of $500] +++File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report++24.6.14.2 Budgets and subaccounts+.................................++You can add budgets to any account in your account hierarchy. If you+have budgets on both parent account and some of its children, then+budget(s) of the child account(s) would be added to the budget of their+parent, much like account balances behave.++ In the most simple case this means that once you add a budget to any+account, all its parents would have budget as well.++ To illustrate this, consider the following budget:++~ monthly from 2019/01+ expenses:personal $1,000.00+ expenses:personal:electronics $100.00+ liabilities++ With this, monthly budget for electronics is defined to be $100 and+budget for personal expenses is an additional $1000, which implicitly+means that budget for both ‘expenses:personal’ and ‘expenses’ is $1100.++ Transactions in ‘expenses:personal:electronics’ will be counted both+towards its $100 budget and $1100 of ‘expenses:personal’ , and+transactions in any other subaccount of ‘expenses:personal’ would be+counted towards only towards the budget of ‘expenses:personal’.++ For example, let’s consider these transactions:++~ monthly from 2019/01+ expenses:personal $1,000.00+ expenses:personal:electronics $100.00+ liabilities++2019/01/01 Google home hub+ expenses:personal:electronics $90.00+ liabilities $-90.00++2019/01/02 Phone screen protector+ expenses:personal:electronics:upgrades $10.00+ liabilities++2019/01/02 Weekly train ticket+ expenses:personal:train tickets $153.00+ liabilities++2019/01/03 Flowers+ expenses:personal $30.00+ liabilities++ As you can see, we have transactions in+‘expenses:personal:electronics:upgrades’ and ‘expenses:personal:train+tickets’, and since both of these accounts are without explicitly+defined budget, these transactions would be counted towards budgets of+‘expenses:personal:electronics’ and ‘expenses:personal’ accordingly:++$ hledger balance --budget -M+Budget performance in 2019/01:++ || Jan +===============================++===============================+ expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] +-------------------------------++-------------------------------+ || 0 [ 0] ++ And with ‘--empty’, we can get a better picture of budget allocation+and consumption:++$ hledger balance --budget -M --empty+Budget performance in 2019/01:++ || Jan +========================================++===============================+ expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] +----------------------------------------++-------------------------------+ || 0 [ 0] +++File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report++24.6.14.3 Selecting budget goals+................................++The budget report evaluates periodic transaction rules to generate+special "goal transactions", which generate the goal amounts for each+account in each report subperiod. When troubleshooting, you can use+‘print --forecast’ to show these as forecasted transactions:++$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated++ By default, the budget report uses all available periodic transaction+rules to generate goals. This includes rules with a different report+interval from your report. Eg if you have daily, weekly and monthly+periodic rules, all of these will contribute to the goals in a monthly+budget report.++ You can select a subset of periodic rules by providing an argument to+the ‘--budget’ flag. ‘--budget=DESCPAT’ will match all periodic rules+whose description contains DESCPAT, a case-insensitive substring (not a+regular expression or query). This means you can give your periodic+rules descriptions (remember that two spaces are needed), and then+select from multiple budgets defined in your journal.+++File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report++24.6.14.4 Budget vs forecast+............................++‘hledger --forecast ...’ and ‘hledger balance --budget ...’ are separate+features, though both of them use the periodic transaction rules defined+in the journal, and both of them generate temporary transactions for+reporting purposes ("forecast transactions" and "budget goal+transactions", respectively). You can use both features at the same+time if you want. Here are some differences between them, as of hledger+1.29:++ CLI:++ • –forecast is a general hledger option, usable with any command+ • –budget is a ‘balance’ command option, usable only with that+ command.++ Visibility of generated transactions:++ • forecast transactions are visible in any report, like ordinary+ transactions+ • budget goal transactions are invisible except for the goal amounts+ they produce in –budget reports.++ Periodic transaction rules:++ • –forecast uses all available periodic transaction rules+ • –budget uses all periodic rules (‘--budget’) or a selected subset+ (‘--budget=DESCPAT’)++ Period of generated transactions:++ • –forecast generates forecast transactions+ • from after the last regular transaction to the end of the+ report period (‘--forecast’)+ • or, during a specified period (‘--forecast=PERIODEXPR’)+ • possibly further restricted by a period specified in the+ periodic transaction rule+ • and always restricted within the bounds of the report period++ • –budget generates budget goal transactions+ • throughout the report period+ • possibly restricted by a period specified in the periodic+ transaction rule.+++File: hledger.info, Node: Data layout, Next: Useful balance reports, Prev: Budget report, Up: balance++24.6.15 Data layout+-------------------++The ‘--layout’ option affects how balance reports show multi-commodity+amounts and commodity symbols, which can improve readability. It can+also normalise the data for easy consumption by other programs. It has+four possible values:++ • ‘--layout=wide[,WIDTH]’: commodities are shown on a single line,+ optionally elided to WIDTH+ • ‘--layout=tall’: each commodity is shown on a separate line+ • ‘--layout=bare’: commodity symbols are in their own column, amounts+ are bare numbers+ • ‘--layout=tidy’: data is normalised to easily-consumed "tidy" form,+ with one row per data value++ Here are the ‘--layout’ modes supported by each output format; note+only CSV output supports all of them:++- txt csv html json sql+---------------------------------------+wide Y Y Y+tall Y Y Y+bare Y Y Y+tidy Y++ Examples:++ • Wide layout. With many commodities, reports can be very wide:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide+ Balance changes in 2012-01-01..2014-12-31:+ + || 2012 2013 2014 Total + ==================++====================================================================================================================================================================================================================+ Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT ++ • Limited wide layout. A width limit reduces the width, but some+ commodities will be hidden:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32+ Balance changes in 2012-01-01..2014-12-31:+ + || 2012 2013 2014 Total + ==================++===========================================================================================================================+ Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + ------------------++---------------------------------------------------------------------------------------------------------------------------+ || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. ++ • Tall layout. Each commodity gets a new line (may be different in+ each column), and account names are repeated:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall+ Balance changes in 2012-01-01..2014-12-31:+ + || 2012 2013 2014 Total + ==================++==================================================+ Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT + ------------------++--------------------------------------------------+ || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT ++ • Bare layout. Commodity symbols are kept in one column, each+ commodity gets its own report row, account names are repeated:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare+ Balance changes in 2012-01-01..2014-12-31:+ + || Commodity 2012 2013 2014 Total + ==================++=============================================+ Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 + ------------------++---------------------------------------------+ || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 ++ • Bare layout also affects CSV output, which is useful for producing+ data that is easier to consume, eg for making charts:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare+ "account","commodity","balance"+ "Assets:US:ETrade","GLD","70.00"+ "Assets:US:ETrade","ITOT","17.00"+ "Assets:US:ETrade","USD","5120.50"+ "Assets:US:ETrade","VEA","36.00"+ "Assets:US:ETrade","VHT","294.00"+ "total","GLD","70.00"+ "total","ITOT","17.00"+ "total","USD","5120.50"+ "total","VEA","36.00"+ "total","VHT","294.00"++ • Tidy layout produces normalised "tidy data", where every variable+ has its own column and each row represents a single data point.+ See+ https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html+ for more. This is the easiest kind of data for other software to+ consume. Here’s how it looks:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy+ "account","period","start_date","end_date","commodity","value"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"+++File: hledger.info, Node: Useful balance reports, Prev: Data layout, Up: balance++24.6.16 Useful balance reports+------------------------------++Some frequently used ‘balance’ options/reports are:++ • ‘bal -M revenues expenses’+ Show revenues/expenses in each month. Also available as the+ ‘incomestatement’ command.++ • ‘bal -M -H assets liabilities’+ Show historical asset/liability balances at each month end. Also+ available as the ‘balancesheet’ command.++ • ‘bal -M -H assets liabilities equity’+ Show historical asset/liability/equity balances at each month end.+ Also available as the ‘balancesheetequity’ command.++ • ‘bal -M assets not:receivable’+ Show changes to liquid assets in each month. Also available as the+ ‘cashflow’ command.++ Also:++ • ‘bal -M expenses -2 -SA’+ Show monthly expenses summarised to depth 2 and sorted by average+ amount.++ • ‘bal -M --budget expenses’+ Show monthly expenses and budget goals.++ • ‘bal -M --valuechange investments’+ Show monthly change in market value of investment assets.++ • ‘bal investments --valuechange -D date:lastweek amt:'>1000' -STA+ [--invert]’+ Show top gainers [or losers] last week+++File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS++24.7 balancesheet+=================++(bs)++ This command displays a balance sheet, showing historical ending+balances of asset and liability accounts. (To see equity as well, use+the balancesheetequity command.) Amounts are shown with normal positive+sign, as in conventional financial statements.++ This report shows accounts declared with the ‘Asset’, ‘Cash’ or+‘Liability’ type (see account types). Or if no such accounts are+declared, it shows top-level accounts named ‘asset’ or ‘liability’ (case+insensitive, plurals allowed) and their subaccounts.++ Example:++$ hledger balancesheet+Balance Sheet++Assets:+ $-1 assets+ $1 bank:saving+ $-2 cash+--------------------+ $-1++Liabilities:+ $1 liabilities:debts+--------------------+ $1++Total:+--------------------+ 0++ This command is a higher-level variant of the ‘balance’ command, and+supports many of that command’s features, such as multi-period reports.+It is similar to ‘hledger balance -H assets liabilities’, but with+smarter account detection, and liabilities displayed with their sign+flipped.++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, ‘html’, and+(experimental) ‘json’.+++File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS++24.8 balancesheetequity+=======================++(bse)++ This command displays a balance sheet, showing historical ending+balances of asset, liability and equity accounts. Amounts are shown+with normal positive sign, as in conventional financial statements.++ This report shows accounts declared with the ‘Asset’, ‘Cash’,+‘Liability’ or ‘Equity’ type (see account types). Or if no such+accounts are declared, it shows top-level accounts named ‘asset’,+‘liability’ or ‘equity’ (case insensitive, plurals allowed) and their+subaccounts.++ Example:++$ hledger balancesheetequity+Balance Sheet With Equity++Assets:+ $-2 assets+ $1 bank:saving+ $-3 cash+--------------------+ $-2++Liabilities:+ $1 liabilities:debts+--------------------+ $1++Equity:+ $1 equity:owner+--------------------+ $1++Total:+--------------------+ 0++ This command is a higher-level variant of the ‘balance’ command, and+supports many of that command’s features, such as multi-period reports.+It is similar to ‘hledger balance -H assets liabilities equity’, but+with smarter account detection, and liabilities/equity displayed with+their sign flipped.++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, ‘html’, and+(experimental) ‘json’.+++File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS++24.9 cashflow+=============++(cf)++ This command displays a cashflow statement, showing the inflows and+outflows affecting "cash" (ie, liquid, easily convertible) assets.+Amounts are shown with normal positive sign, as in conventional+financial statements.++ This report shows accounts declared with the ‘Cash’ type (see account+types). Or if no such accounts are declared, it shows accounts++ • under a top-level account named ‘asset’ (case insensitive, plural+ allowed)+ • whose name contains some variation of ‘cash’, ‘bank’, ‘checking’ or+ ‘saving’.++ More precisely: all accounts matching this case insensitive regular+expression:++ ‘^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)’++ and their subaccounts.++ An example cashflow report:++$ hledger cashflow+Cashflow Statement++Cash flows:+ $-1 assets+ $1 bank:saving+ $-2 cash+--------------------+ $-1++Total:+--------------------+ $-1++ This command is a higher-level variant of the ‘balance’ command, and+supports many of that command’s features, such as multi-period reports.+It is similar to ‘hledger balance assets not:fixed not:investment+not:receivable’, but with smarter account detection.++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, ‘html’, and+(experimental) ‘json’.+++File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS++24.10 check+===========++Check for various kinds of errors in your data.++ hledger provides a number of built-in error checks to help prevent+problems in your data. Some of these are run automatically; or, you can+use this ‘check’ command to run them on demand, with no output and a+zero exit code if all is well. Specify their names (or a prefix) as+argument(s).++ Some examples:++hledger check # basic checks+hledger check -s # basic + strict checks+hledger check ordereddates payees # basic + two other checks++ If you are an Emacs user, you can also configure flycheck-hledger to+run these checks, providing instant feedback as you edit the journal.++ Here are the checks currently available:++* Menu:++* Basic checks::+* Strict checks::+* Other checks::+* Custom checks::+* More about specific checks::+++File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check++24.10.1 Basic checks+--------------------++These checks are always run automatically, by (almost) all hledger+commands, including ‘check’:++ • *parseable* - data files are well-formed and can be successfully+ parsed++ • *balancedwithautoconversion* - all transactions are balanced,+ inferring missing amounts where necessary, and possibly converting+ commodities using costs or automatically-inferred costs++ • *assertions* - all balance assertions in the journal are passing.+ (This check can be disabled with ‘-I’/‘--ignore-assertions’.)+++File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check++24.10.2 Strict checks+---------------------++These additional checks are run when the ‘-s’/‘--strict’ (strict mode)+flag is used. Or, they can be run by giving their names as arguments to+‘check’:++ • *accounts* - all account names used by transactions have been+ declared++ • *commodities* - all commodity symbols used have been declared++ • *balancednoautoconversion* - transactions are balanced, possibly+ using explicit costs but not inferred ones+++File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check++24.10.3 Other checks+--------------------++These checks can be run only by giving their names as arguments to+‘check’. They are more specialised and not desirable for everyone,+therefore optional:++ • *ordereddates* - transactions are ordered by date within each file++ • *payees* - all payees used by transactions have been declared++ • *recentassertions* - all accounts with balance assertions have a+ balance assertion no more than 7 days before their latest posting++ • *tags* - all tags used by transactions have been declared++ • *uniqueleafnames* - all account leaf names are unique+++File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check++24.10.4 Custom checks+---------------------++A few more checks are are available as separate add-on commands, in+https://github.com/simonmichael/hledger/tree/master/bin:++ • *hledger-check-tagfiles* - all tag values containing / (a forward+ slash) exist as file paths++ • *hledger-check-fancyassertions* - more complex balance assertions+ are passing++ You could make similar scripts to perform your own custom checks.+See: Cookbook -> Scripting.+++File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check++24.10.5 More about specific checks+----------------------------------++‘hledger check recentassertions’ will complain if any balance-asserted+account does not have a balance assertion within 7 days before its+latest posting. This aims to prevent the situation where you are+regularly updating your journal, but forgetting to check your balances+against the real world, then one day must dig back through months of+data to find an error. It assumes that adding a balance assertion+requires/reminds you to check the real-world balance. That may not be+true if you auto-generate balance assertions from bank data; in that+case, I recommend to import transactions uncleared, then use the+manual-review-and-mark-cleared phase as a reminder to check the latest+assertions against real-world balances.+++File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS++24.11 close+===========++‘close [--retain | --migrate | --open] [QUERY]’++ By default: prints a transaction that zeroes out ("closes") all+accounts, transferring their balances to an equity account. Query+arguments can be added to override the accounts selection. Three other+modes are supported:++ ‘--retain’: prints a transaction closing revenue and expense+balances. This is traditionally done by businesses at the end of each+accounting period; it is less necessary in personal and computer-based+accounting, but it can help balance the accounting equation A=L+E.++ ‘--migrate’: prints a transaction to close asset, liability and most+equity balances, and another transaction to re-open them. This can be+useful when starting a new file (for performance or data protection).+Adding the closing transaction to the old file allows old and new files+to be combined.++ ‘--open’: as above, but prints just the opening transaction. This+can be useful for starting a new file, leaving the old file unchanged.+Similar to Ledger’s equity command.++ You can change the equity account name with ‘--close-acct ACCT’. It+defaults to ‘equity:retained earnings’ with ‘--retain’, or+‘equity:opening/closing balances’ otherwise.++ You can change the transaction description(s) with ‘--close-desc+'DESC'’ and ‘--open-desc 'DESC'’. It defaults to ‘retain earnings’ with+‘--retain’, or ‘closing balances’ and ‘opening balances’ otherwise.++ Just one posting to the equity account will be used by default, with+an implicit amount.++ With ‘--x/--explicit’ the amount will be shown explicitly, and if it+involves multiple commodities, a separate posting will be generated for+each commodity.++ With ‘--interleaved’, each equity posting is shown next to the+corresponding source/destination posting.++ The default closing date is yesterday or the journal’s end date,+whichever is later. You can change this by specifying a report end+date; the last day of the report period will be the closing date. Eg+‘-e 2022’ means "close on 2022-12-31".++ The default closing date is yesterday, or the journal’s end date,+whichever is later. You can change this by specifying a report end+date; (The report start date does not matter.) The last day of the+report period will be the closing date; eg ‘-e 2022’ means "close on+2022-12-31". The opening date is always the day after the closing date.++* Menu:++* close and costs::+* close and balance assertions::+* Example retain earnings::+* Example migrate balances to a new file::+* Example excluding closing/opening transactions::+++File: hledger.info, Node: close and costs, Next: close and balance assertions, Up: close++24.11.1 close and costs+-----------------------++With ‘--show-costs’, any amount costs are shown, with separate postings+for each cost. (This currently the best way to view investment assets,+showing lots and cost bases.) If you have many currency conversion or+investment transactions, it can generate very large journal entries.+++File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Prev: close and costs, Up: close++24.11.2 close and balance assertions+------------------------------------++Balance assertions will be generated, verifying that the accounts have+been reset to zero (and then restored to their previous balances, if+there is an opening transaction).++ These provide useful error checking, but you can ignore them+temporarily with ‘-I’, or remove them if you prefer.++ You probably should avoid filtering transactions by status or+realness (‘-C’, ‘-R’, ‘status:’), or generating postings (‘--auto’),+with this command, since the balance assertions would depend on these.++ Note custom posting dates spanning the file boundary will disrupt the+balance assertions:++2023-12-30 a purchase made in december, cleared in january+ expenses:food 5+ assets:bank:checking -5 ; date: 2023-01-02++ To solve that you can transfer the money to and from a temporary+account, in effect splitting the multi-day transaction into two+single-day transactions:++; in 2022.journal:+2022-12-30 a purchase made in december, cleared in january+ expenses:food 5+ equity:pending -5++; in 2023.journal:+2023-01-02 last year's transaction cleared+ equity:pending 5 = 0+ assets:bank:checking -5+++File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close++24.11.3 Example: retain earnings+--------------------------------++Record 2022’s revenues/expenses as retained earnings on 2022-12-31,+appending the generated transaction to the journal:++$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal++ Now 2022’s income statement will show only zeroes. To see it again,+exclude the retain transaction. Eg:++$ hledger -f 2022.journal is not:desc:'retain earnings'+++File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close++24.11.4 Example: migrate balances to a new file+-----------------------------------------------++Close assets/liabilities/equity on 2022-12-31 and re-open them on+2023-01-01:++$ hledger close --migrate -f 2022.journal -p 2022+# copy/paste the closing transaction to the end of 2022.journal+# copy/paste the opening transaction to the start of 2023.journal++ Now 2022’s balance sheet will show only zeroes, indicating a balanced+accounting equation. (Unless you are using @/@@ notation - in that+case, try adding –infer-equity.) To see it again, exclude the closing+transaction. Eg:++$ hledger -f 2022.journal bs not:desc:'closing balances'+++File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close++24.11.5 Example: excluding closing/opening transactions+-------------------------------------------------------++When combining many files for multi-year reports, the closing/opening+transactions cause some noise in reports like ‘print’ and ‘register’.+You can exclude them as shown above, but ‘not:desc:...’ could be+fragile, and also you will need to avoid excluding the very first+opening transaction, which can be awkward. Here is a way to do it,+using tags: add ‘clopen:’ tags to all opening/closing balances+transactions except the first, like this:++; 2021.journal+2021-06-01 first opening balances+...+2021-12-31 closing balances ; clopen:2022+...++; 2022.journal+2022-01-01 opening balances ; clopen:2022+...+2022-12-31 closing balances ; clopen:2023+...++; 2023.journal+2023-01-01 opening balances ; clopen:2023+...++ Now, assuming a combined journal like:++; all.journal+include 2021.journal+include 2022.journal+include 2023.journal++ The ‘clopen:’ tag can exclude all but the first opening transaction.+To show a clean multi-year checking register:++$ hledger -f all.journal areg checking not:tag:clopen++ And the year values allow more precision. To show 2022’s year-end+balance sheet:++$ hledger -f all.journal bs -e2023 not:tag:clopen=2023+++File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS++24.12 codes+===========++List the codes seen in transactions, in the order parsed.++ This command prints the value of each transaction’s code field, in+the order transactions were parsed. The transaction code is an optional+value written in parentheses between the date and description, often+used to store a cheque number, order number or similar.++ Transactions aren’t required to have a code, and missing or empty+codes will not be shown by default. With the ‘-E’/‘--empty’ flag, they+will be printed as blank lines.++ You can add a query to select a subset of transactions.++ Examples:++2022/1/1 (123) Supermarket + Food $5.00+ Checking ++2022/1/2 (124) Post Office+ Postage $8.32+ Checking++2022/1/3 Supermarket+ Food $11.23+ Checking ++2022/1/4 (126) Post Office+ Postage $3.21+ Checking++$ hledger codes+123+124+126++$ hledger codes -E+123+124++126+++File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: PART 4 COMMANDS++24.13 commodities+=================++List all commodity/currency symbols used or declared in the journal.+++File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: PART 4 COMMANDS++24.14 descriptions+==================++List the unique descriptions that appear in transactions.++ This command lists the unique descriptions that appear in+transactions, in alphabetic order. You can add a query to select a+subset of transactions.++ Example:++$ hledger descriptions+Store Name+Gas Station | Petrol+Person A+++File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS++24.15 diff+==========++Compares a particular account’s transactions in two input files. It+shows any transactions to this account which are in one file but not in+the other.++ More precisely, for each posting affecting this account in either+file, it looks for a corresponding posting in the other file which posts+the same amount to the same account (ignoring date, description, etc.)+Since postings not transactions are compared, this also works when+multiple bank transactions have been combined into a single journal+entry.++ This is useful eg if you have downloaded an account’s transactions+from your bank (eg as CSV data). When hledger and your bank disagree+about the account balance, you can compare the bank data with your+journal to find out the cause.++ Examples:++$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only:++2014/01/01 Opening Balances+ assets:bank:giro EUR ...+ ...+ equity:opening balances EUR -...++These transactions are in the second file only:+++File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS++24.16 files+===========++List all files included in the journal. With a REGEX argument, only+file names matching the regular expression (case sensitive) are shown.+++File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS++24.17 help+==========++Show the hledger user manual in the terminal, with ‘info’, ‘man’, or a+pager. With a TOPIC argument, open it at that topic if possible. TOPIC+can be any heading in the manual, or a heading prefix, case insensitive.+Eg: ‘commands’, ‘print’, ‘forecast’, ‘journal’, ‘amount’, ‘"auto+postings"’.++ This command shows the hledger manual built in to your hledger+version. It can be useful when offline, or when you prefer the terminal+to a web browser, or when the appropriate hledger manual or viewing+tools are not installed on your system.++ By default it chooses the best viewer found in $PATH (preferring info+since the hledger manual is large). You can select a particular viewer+with the ‘-i’, ‘-m’, or ‘-p’ flags.++ Examples++$ hledger help --help # show how the help command works+$ hledger help # show the hledger manual with info, man or $PAGER+$ hledger help journal # show the journal topic in the hledger manual+++File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS++24.18 import+============++Read new transactions added to each FILE since last run, and add them to+the journal. Or with –dry-run, just print the transactions that would+be added. Or with –catchup, just mark all of the FILEs’ transactions as+imported, without actually importing any.++ This command may append new transactions to the main journal file+(which should be in journal format). Existing transactions are not+changed. This is one of the few hledger commands that writes to the+journal file (see also ‘add’).++ Unlike other hledger commands, with ‘import’ the journal file is an+output file, and will be modified, though only by appending (existing+data will not be changed). The input files are specified as arguments,+so to import one or more CSV files to your main journal, you will run+‘hledger import bank.csv’ or perhaps ‘hledger import *.csv’.++ Note you can import from any file format, though CSV files are the+most common import source, and these docs focus on that case.++* Menu:++* Deduplication::+* Import testing::+* Importing balance assignments::+* Commodity display styles::+++File: hledger.info, Node: Deduplication, Next: Import testing, Up: import++24.18.1 Deduplication+---------------------++As a convenience ‘import’ does _deduplication_ while reading+transactions. This does not mean "ignore transactions that look the+same", but rather "ignore transactions that have been seen before".+This is intended for when you are periodically importing foreign data+which may contain already-imported transactions. So eg, if every day+you download bank CSV files containing redundant data, you can safely+run ‘hledger import bank.csv’ and only new transactions will be+imported. (‘import’ is idempotent.)++ Since the items being read (CSV records, eg) often do not come with+unique identifiers, hledger detects new transactions by date, assuming+that:++ 1. new items always have the newest dates+ 2. item dates do not change across reads+ 3. and items with the same date remain in the same relative order+ across reads.++ These are often true of CSV files representing transactions, or true+enough so that it works pretty well in practice. 1 is important, but+violations of 2 and 3 amongst the old transactions won’t matter (and if+you import often, the new transactions will be few, so less likely to be+the ones affected).++ hledger remembers the latest date processed in each input file by+saving a hidden ".latest" state file in the same directory. Eg when+reading ‘finance/bank.csv’, it will look for and update the+‘finance/.latest.bank.csv’ state file. The format is simple: one or+more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I+have processed transactions up to this date, and this many of them on+that date." Normally you won’t see or manipulate these state files+yourself. But if needed, you can delete them to reset the state (making+all transactions "new"), or you can construct them to "catch up" to a+certain date.++ Note deduplication (and updating of state files) can also be done by+‘print --new’, but this is less often used.+++File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import++24.18.2 Import testing+----------------------++With ‘--dry-run’, the transactions that will be imported are printed to+the terminal, without updating your journal or state files. The output+is valid journal format, like the print command, so you can re-parse it.+Eg, to see any importable transactions which CSV rules have not+categorised:++$ hledger import --dry bank.csv | hledger -f- -I print unknown++ or (live updating):++$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'++ Note: when importing from multiple files at once, it’s currently+possible for some .latest files to be updated successfully, while the+actual import fails because of a problem in one of the files, leaving+them out of sync (and causing some transactions to be missed). To+prevent this, do a –dry-run first and fix any problems before the real+import.+++File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import++24.18.3 Importing balance assignments+-------------------------------------++Entries added by import will have their posting amounts made explicit+(like ‘hledger print -x’). This means that any balance assignments in+imported files must be evaluated; but, imported files don’t get to see+the main file’s account balances. As a result, importing entries with+balance assignments (eg from an institution that provides only balances+and not posting amounts) will probably generate incorrect posting+amounts. To avoid this problem, use print instead of import:++$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE++ (If you think import should leave amounts implicit like print does,+please test it and send a pull request.)+++File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import++24.18.4 Commodity display styles+--------------------------------++Imported amounts will be formatted according to the canonical commodity+styles (declared or inferred) in the main journal file.+++File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS++24.19 incomestatement+=====================++(is)++ This command displays an income statement, showing revenues and+expenses during one or more periods. Amounts are shown with normal+positive sign, as in conventional financial statements.++ This report shows accounts declared with the ‘Revenue’ or ‘Expense’+type (see account types). Or if no such accounts are declared, it shows+top-level accounts named ‘revenue’ or ‘income’ or ‘expense’ (case+insensitive, plurals allowed) and their subaccounts.++ Example:++$ hledger incomestatement+Income Statement++Revenues:+ $-2 income+ $-1 gifts+ $-1 salary+--------------------+ $-2++Expenses:+ $2 expenses+ $1 food+ $1 supplies+--------------------+ $2++Total:+--------------------+ 0++ This command is a higher-level variant of the ‘balance’ command, and+supports many of that command’s features, such as multi-period reports.+It is similar to ‘hledger balance '(revenues|income)' expenses’, but+with smarter account detection, and revenues/income displayed with their+sign flipped.++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, ‘html’, and+(experimental) ‘json’.+++File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS++24.20 notes+===========++List the unique notes that appear in transactions.++ This command lists the unique notes that appear in transactions, in+alphabetic order. You can add a query to select a subset of+transactions. The note is the part of the transaction description after+a | character (or if there is no |, the whole description).++ Example:++$ hledger notes+Petrol+Snacks+++File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS++24.21 payees+============++List the unique payee/payer names that appear in transactions.++ This command lists unique payee/payer names which have been declared+with payee directives (–declared), used in transaction descriptions+(–used), or both (the default).++ The payee/payer is the part of the transaction description before a |+character (or if there is no |, the whole description).++ You can add query arguments to select a subset of transactions. This+implies –used.++ Example:++$ hledger payees+Store Name+Gas Station+Person A+++File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS++24.22 prices+============++Print market price directives from the journal. With+–infer-market-prices, generate additional market prices from costs.+With –infer-reverse-prices, also generate market prices by inverting+known prices. Prices can be filtered by a query. Price amounts are+displayed with their full precision.+++File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS++24.23 print+===========++Show transaction journal entries, sorted by date.++ The print command displays full journal entries (transactions) from+the journal file, sorted by date (or with ‘--date2’, by secondary date).++ Amounts are shown mostly normalised to commodity display style, eg+the placement of commodity symbols will be consistent. All of their+decimal places are shown, as in the original journal entry (with one+alteration: in some cases trailing zeroes are added.)++ Amounts are shown right-aligned within each transaction (but not+across all transactions).++ Directives and inter-transaction comments are not shown, currently.+This means the print command is somewhat lossy, and if you are using it+to reformat your journal you should take care to also copy over the+directives and file-level comments.++ Eg:++$ hledger print+2008/01/01 income+ assets:bank:checking $1+ income:salary $-1++2008/06/01 gift+ assets:bank:checking $1+ income:gifts $-1++2008/06/02 save+ assets:bank:saving $1+ assets:bank:checking $-1++2008/06/03 * eat & shop+ expenses:food $1+ expenses:supplies $1+ assets:cash $-2++2008/12/31 * pay off+ liabilities:debts $1+ assets:bank:checking $-1++ print’s output is usually a valid hledger journal, and you can+process it again with a second hledger command. This can be useful for+certain kinds of search, eg:++# Show running total of food expenses paid from cash.+# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.+$ hledger print assets:cash | hledger -f- -I reg expenses:food++ There are some situations where print’s output can become+unparseable:++ • Valuation affects posting amounts but not balance assertion or+ balance assignment amounts, potentially causing those to fail.+ • Auto postings can generate postings with too many missing amounts.+ • Account aliases can generate bad account names.++ Normally, the journal entry’s explicit or implicit amount style is+preserved. For example, when an amount is omitted in the journal, it+will not appear in the output. Similarly, when a cost is implied but+not written, it will not appear in the output. You can use the+‘-x’/‘--explicit’ flag to make all amounts and costs explicit, which can+be useful for troubleshooting or for making your journal more readable+and robust against data entry errors. ‘-x’ is also implied by using any+of ‘-B’,‘-V’,‘-X’,‘--value’.++ Note, ‘-x’/‘--explicit’ will cause postings with a multi-commodity+amount (these can arise when a multi-commodity transaction has an+implicit amount) to be split into multiple single-commodity postings,+keeping the output parseable.++ With ‘-B’/‘--cost’, amounts with costs are converted to cost using+that price. This can be used for troubleshooting.++ With ‘-m DESC’/‘--match=DESC’, print does a fuzzy search for one+recent transaction whose description is most similar to DESC. DESC+should contain at least two characters. If there is no similar-enough+match, no transaction will be shown and the program exit code will be+non-zero.++ With ‘--new’, hledger prints only transactions it has not seen on a+previous run. This uses the same deduplication system as the ‘import’+command. (See import’s docs for details.)++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, and+(experimental) ‘json’ and ‘sql’.++ Here’s an example of print’s CSV output:++$ hledger print -Ocsv+"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"+"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""+"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""+"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""+"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""+"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""+"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""+"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""+"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""+"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""+"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""+"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""++ • There is one CSV record per posting, with the parent transaction’s+ fields repeated.+ • The "txnidx" (transaction index) field shows which postings belong+ to the same transaction. (This number might change if transactions+ are reordered within the file, files are parsed/included in a+ different order, etc.)+ • The amount is separated into "commodity" (the symbol) and "amount"+ (numeric quantity) fields.+ • The numeric amount is repeated in either the "credit" or "debit"+ column, for convenience. (Those names are not accurate in the+ accounting sense; it just puts negative amounts under credit and+ zero or greater amounts under debit.)+++File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS++24.24 register+==============++(reg)++ Show postings and their running total.++ The register command displays matched postings, across all accounts,+in date order, with their running total or running historical balance.+(See also the ‘aregister’ command, which shows matched transactions in a+specific account.)++ register normally shows line per posting, but note that+multi-commodity amounts will occupy multiple lines (one line per+commodity).++ It is typically used with a query selecting a particular account, to+see that account’s activity:++$ hledger register checking+2008/01/01 income assets:bank:checking $1 $1+2008/06/01 gift assets:bank:checking $1 $2+2008/06/02 save assets:bank:checking $-1 $1+2008/12/31 pay off assets:bank:checking $-1 0++ With ‘--date2’, it shows and sorts by secondary date instead.++ For performance reasons, column widths are chosen based on the first+1000 lines; this means unusually wide values in later lines can cause+visual discontinuities as column widths are adjusted. If you want to+ensure perfect alignment, at the cost of more time and memory, use the+‘--align-all’ flag.++ The ‘--historical’/‘-H’ flag adds the balance from any undisplayed+prior postings to the running total. This is useful when you want to+see only recent activity, with a historically accurate running balance:++$ hledger register checking -b 2008/6 --historical+2008/06/01 gift assets:bank:checking $1 $2+2008/06/02 save assets:bank:checking $-1 $1+2008/12/31 pay off assets:bank:checking $-1 0++ The ‘--depth’ option limits the amount of sub-account detail+displayed.++ The ‘--average’/‘-A’ flag shows the running average posting amount+instead of the running total (so, the final number displayed is the+average for the whole report period). This flag implies ‘--empty’ (see+below). It is affected by ‘--historical’. It works best when showing+just one account and one commodity.++ The ‘--related’/‘-r’ flag shows the _other_ postings in the+transactions of the postings which would normally be shown.++ The ‘--invert’ flag negates all amounts. For example, it can be used+on an income account where amounts are normally displayed as negative+numbers. It’s also useful to show postings on the checking account+together with the related account:++$ hledger register --related --invert assets:checking++ With a reporting interval, register shows summary postings, one per+interval, aggregating the postings to each account:++$ hledger register --monthly income+2008/01 income:salary $-1 $-1+2008/06 income:gifts $-1 $-2++ Periods with no activity, and summary postings with a zero amount,+are not shown by default; use the ‘--empty’/‘-E’ flag to see them:++$ hledger register --monthly income -E+2008/01 income:salary $-1 $-1+2008/02 0 $-1+2008/03 0 $-1+2008/04 0 $-1+2008/05 0 $-1+2008/06 income:gifts $-1 $-2+2008/07 0 $-2+2008/08 0 $-2+2008/09 0 $-2+2008/10 0 $-2+2008/11 0 $-2+2008/12 0 $-2++ Often, you’ll want to see just one line per interval. The ‘--depth’+option helps with this, causing subaccounts to be aggregated:++$ hledger register --monthly assets --depth 1h+2008/01 assets $1 $1+2008/06 assets $-1 0+2008/12 assets $-1 $-1++ Note when using report intervals, if you specify start/end dates+these will be adjusted outward if necessary to contain a whole number of+intervals. This ensures that the first and last intervals are full+length and comparable to the others in the report.++ With ‘-m DESC’/‘--match=DESC’, register does a fuzzy search for one+recent posting whose description is most similar to DESC. DESC should+contain at least two characters. If there is no similar-enough match,+no posting will be shown and the program exit code will be non-zero.++* Menu:++* Custom register output::+++File: hledger.info, Node: Custom register output, Up: register++24.24.1 Custom register output+------------------------------++register uses the full terminal width by default, except on windows.+You can override this by setting the ‘COLUMNS’ environment variable (not+a bash shell variable) or by using the ‘--width’/‘-w’ option.++ The description and account columns normally share the space equally+(about half of (width - 40) each). You can adjust this by adding a+description width as part of –width’s argument, comma-separated:+‘--width W,D’ . Here’s a diagram (won’t display correctly in –help):++<--------------------------------- width (W) ---------------------------------->+date (10) description (D) account (W-41-D) amount (12) balance (12)+DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA++ and some examples:++$ hledger reg # use terminal width (or 80 on windows)+$ hledger reg -w 100 # use width 100+$ COLUMNS=100 hledger reg # set with one-time environment variable+$ export COLUMNS=100; hledger reg # set till session end (or window resize)+$ hledger reg -w 100,40 # set overall width 100, description width 40+$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, and+(experimental) ‘json’.+++File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS++24.25 rewrite+=============++Print all transactions, rewriting the postings of matched transactions.+For now the only rewrite available is adding new postings, like print+–auto.++ This is a start at a generic rewriter of transaction entries. It+reads the default journal and prints the transactions, like print, but+adds one or more specified postings to any transactions matching QUERY.+The posting amounts can be fixed, or a multiplier of the existing+transaction’s first posting amount.++ Examples:++$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'+$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'+$ hledger-rewrite.hs -f rewrites.hledger++ rewrites.hledger may consist of entries like:++= ^income amt:<0 date:2017+ (liabilities:tax) *0.33 ; tax on income+ (reserve:grocery) *0.25 ; reserve 25% for grocery+ (reserve:) *0.25 ; reserve 25% for grocery++ Note the single quotes to protect the dollar sign from bash, and the+two spaces between account and amount.++ More:++$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...+$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'+$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'+$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'++ Argument for ‘--add-posting’ option is a usual posting of transaction+with an exception for amount specification. More precisely, you can use+‘'*'’ (star symbol) before the amount to indicate that that this is a+factor for an amount of original matched posting. If the amount+includes a commodity name, the new posting amount will be in the new+commodity; otherwise, it will be in the matched posting amount’s+commodity.++* Menu:++* Re-write rules in a file::+* Diff output format::+* rewrite vs print --auto::+++File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite++24.25.1 Re-write rules in a file+--------------------------------++During the run this tool will execute so called "Automated Transactions"+found in any journal it process. I.e instead of specifying this+operations in command line you can put them in a journal file.++$ rewrite-rules.journal++ Make contents look like this:++= ^income+ (liabilities:tax) *.33++= expenses:gifts+ budget:gifts *-1+ assets:budget *1++ Note that ‘'='’ (equality symbol) that is used instead of date in+transactions you usually write. It indicates the query by which you+want to match the posting to add new ones.++$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal++ This is something similar to the commands pipeline:++$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \+ | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \+ --add-posting 'assets:budget *1' \+ > rewritten-tidy-output.journal++ It is important to understand that relative order of such entries in+journal is important. You can re-use result of previously added+postings.+++File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite++24.25.2 Diff output format+--------------------------++To use this tool for batch modification of your journal files you may+find useful output in form of unified diff.++$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'++ Output might look like:++--- /tmp/examples/sample.journal++++ /tmp/examples/sample.journal+@@ -18,3 +18,4 @@+ 2008/01/01 income+- assets:bank:checking $1++ assets:bank:checking $1+ income:salary++ (liabilities:tax) 0+@@ -22,3 +23,4 @@+ 2008/06/01 gift+- assets:bank:checking $1++ assets:bank:checking $1+ income:gifts++ (liabilities:tax) 0++ If you’ll pass this through ‘patch’ tool you’ll get transactions+containing the posting that matches your query be updated. Note that+multiple files might be update according to list of input files+specified via ‘--file’ options and ‘include’ directives inside of these+files.++ Be careful. Whole transaction being re-formatted in a style of+output from ‘hledger print’.++ See also:++ https://github.com/simonmichael/hledger/issues/99+++File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite++24.25.3 rewrite vs. print –auto+-------------------------------++This command predates print –auto, and currently does much the same+thing, but with these differences:++ • with multiple files, rewrite lets rules in any file affect all+ other files. print –auto uses standard directive scoping; rules+ affect only child files.++ • rewrite’s query limits which transactions can be rewritten; all are+ printed. print –auto’s query limits which transactions are+ printed.++ • rewrite applies rules specified on command line or in the journal.+ print –auto applies rules specified in the journal.+++File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: PART 4 COMMANDS++24.26 roi+=========++Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on+your investments.++ At a minimum, you need to supply a query (which could be just an+account name) to select your investment(s) with ‘--inv’, and another+query to identify your profit and loss transactions with ‘--pnl’.++ If you do not record changes in the value of your investment+manually, or do not require computation of time-weighted return (TWR),+‘--pnl’ could be an empty query (‘--pnl ""’ or ‘--pnl STR’ where ‘STR’+does not match any of your accounts).++ This command will compute and display the internalized rate of return+(IRR) and time-weighted rate of return (TWR) for your investments for+the time period requested. Both rates of return are annualized before+display, regardless of the length of reporting interval.++ Price directives will be taken into account if you supply appropriate+‘--cost’ or ‘--value’ flags (see VALUATION).++ Note, in some cases this report can fail, for these reasons:++ • Error (NotBracketed): No solution for Internal Rate of Return+ (IRR). Possible causes: IRR is huge (>1000000%), balance of+ investment becomes negative at some point in time.+ • Error (SearchFailed): Failed to find solution for Internal Rate of+ Return (IRR). Either search does not converge to a solution, or+ converges too slowly.++ Examples:++ • Using roi to compute total return of investment in stocks:+ https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger++ • Cookbook > Return on Investment: https://hledger.org/roi.html++* Menu:++* Spaces and special characters in --inv and --pnl::+* Semantics of --inv and --pnl::+* IRR and TWR explained::+++File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi++24.26.1 Spaces and special characters in ‘--inv’ and+----------------------------------------------------++‘--pnl’ Note that ‘--inv’ and ‘--pnl’’s argument is a query, and queries+could have several space-separated terms (see QUERIES).++ To indicate that all search terms form single command-line argument,+you will need to put them in quotes (see Special characters):++$ hledger roi --inv 'term1 term2 term3 ...'++ If any query terms contain spaces themselves, you will need an extra+level of nested quoting, eg:++$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"+++File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi++24.26.2 Semantics of ‘--inv’ and ‘--pnl’+----------------------------------------++Query supplied to ‘--inv’ has to match all transactions that are related+to your investment. Transactions not matching ‘--inv’ will be ignored.++ In these transactions, ROI will conside postings that match ‘--inv’+to be "investment postings" and other postings (not matching ‘--inv’)+will be sorted into two categories: "cash flow" and "profit and loss",+as ROI needs to know which part of the investment value is your+contributions and which is due to the return on investment.++ • "Cash flow" is depositing or withdrawing money, buying or selling+ assets, or otherwise converting between your investment commodity+ and any other commodity. Example:++ 2019-01-01 Investing in Snake Oil+ assets:cash -$100+ investment:snake oil+ + 2020-01-01 Selling my Snake Oil+ assets:cash $10+ investment:snake oil = 0++ • "Profit and loss" is change in the value of your investment:++ 2019-06-01 Snake Oil falls in value+ investment:snake oil = $57+ equity:unrealized profit or loss++ All non-investment postings are assumed to be "cash flow", unless+they match ‘--pnl’ query. Changes in value of your investment due to+"profit and loss" postings will be considered as part of your investment+return.++ Example: if you use ‘--inv snake --pnl equity:unrealized’, then+postings in the example below would be classifed as:++2019-01-01 Snake Oil #1+ assets:cash -$100 ; cash flow posting+ investment:snake oil ; investment posting++2019-03-01 Snake Oil #2+ equity:unrealized pnl -$100 ; profit and loss posting+ snake oil ; investment posting++2019-07-01 Snake Oil #3+ equity:unrealized pnl ; profit and loss posting+ cash -$100 ; cash flow posting+ snake oil $50 ; investment posting+++File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi++24.26.3 IRR and TWR explained+-----------------------------++"ROI" stands for "return on investment". Traditionally this was+computed as a difference between current value of investment and its+initial value, expressed in percentage of the initial value.++ However, this approach is only practical in simple cases, where+investments receives no in-flows or out-flows of money, and where rate+of growth is fixed over time. For more complex scenarios you need+different ways to compute rate of return, and this command implements+two of them: IRR and TWR.++ Internal rate of return, or "IRR" (also called "money-weighted rate+of return") takes into account effects of in-flows and out-flows.+Naively, if you are withdrawing from your investment, your future gains+would be smaller (in absolute numbers), and will be a smaller percentage+of your initial investment, and if you are adding to your investment,+you will receive bigger absolute gains (but probably at the same rate of+return). IRR is a way to compute rate of return for each period between+in-flow or out-flow of money, and then combine them in a way that gives+you a compound annual rate of return that investment is expected to+generate.++ As mentioned before, in-flows and out-flows would be any cash that+you personally put in or withdraw, and for the "roi" command, these are+the postings that match the query in the‘--inv’ argument and NOT match+the query in the‘--pnl’ argument.++ If you manually record changes in the value of your investment as+transactions that balance them against "profit and loss" (or "unrealized+gains") account or use price directives, then in order for IRR to+compute the precise effect of your in-flows and out-flows on the rate of+return, you will need to record the value of your investement on or+close to the days when in- or out-flows occur.++ In technical terms, IRR uses the same approach as computation of net+present value, and tries to find a discount rate that makes net present+value of all the cash flows of your investment to add up to zero. This+could be hard to wrap your head around, especially if you haven’t done+discounted cash flow analysis before. Implementation of IRR in hledger+should produce results that match the ‘XIRR’ formula in Excel.++ Second way to compute rate of return that ‘roi’ command implements is+called "time-weighted rate of return" or "TWR". Like IRR, it will also+break the history of your investment into periods between in-flows,+out-flows and value changes, to compute rate of return per each period+and then a compound rate of return. However, internal workings of TWR+are quite different.++ TWR represents your investment as an imaginary "unit fund" where+in-flows/ out-flows lead to buying or selling "units" of your investment+and changes in its value change the value of "investment unit". Change+in "unit price" over the reporting period gives you rate of return of+your investment.++ References:++ • Explanation of rate of return+ • Explanation of IRR+ • Explanation of TWR+ • Examples of computing IRR and TWR and discussion of the limitations+ of both metrics+++File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS++24.27 stats+===========++Show journal and performance statistics.++ The stats command displays summary information for the whole journal,+or a matched part of it. With a reporting interval, it shows a report+for each report period.++ At the end, it shows (in the terminal) the overall run time and+number of transactions processed per second. Note these are approximate+and will vary based on machine, current load, data size, hledger+version, haskell lib versions, GHC version.. but they may be of+interest. The ‘stats’ command’s run time is similar to that of a+single-column balance report.++ Example:++$ hledger stats -f examples/1000x1000x10.journal+Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal+Included files : +Transactions span : 2000-01-01 to 2002-09-27 (1000 days)+Last transaction : 2002-09-26 (6995 days ago)+Transactions : 1000 (1.0 per day)+Transactions last 30 days: 0 (0.0 per day)+Transactions last 7 days : 0 (0.0 per day)+Payees/descriptions : 1000+Accounts : 1000 (depth 10)+Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)+Market prices : 1000 (A)++Run time : 0.12 s+Throughput : 8342 txns/s++ This command supports the -o/–output-file option (but not+-O/–output-format selection).+++File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS++24.28 tags+==========++List the tags used in the journal, or their values.++ This command lists the tag names used in the journal, whether on+transactions, postings, or account declarations.++ With a TAGREGEX argument, only tag names matching this regular+expression (case insensitive, infix matched) are shown.++ With QUERY arguments, only transactions and accounts matching this+query are considered. If the query involves transaction fields (date:,+desc:, amt:, ...), the search is restricted to the matched transactions+and their accounts.++ With the –values flag, the tags’ unique non-empty values are listed+instead. With -E/–empty, blank/empty values are also shown.++ With –parsed, tags or values are shown in the order they were parsed,+with duplicates included. (Except, tags from account declarations are+always shown first.)++ Tip: remember, accounts also acquire tags from their parents,+postings also acquire tags from their account and transaction,+transactions also acquire tags from their postings.+++File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS++24.29 test+==========++Run built-in unit tests.++ This command runs the unit tests built in to hledger and hledger-lib,+printing the results on stdout. If any test fails, the exit code will+be non-zero.++ This is mainly used by hledger developers, but you can also use it to+sanity-check the installed hledger executable on your platform. All+tests are expected to pass - if you ever see a failure, please report as+a bug!++ This command also accepts tasty test runner options, written after a+– (double hyphen). Eg to run only the tests in Hledger.Data.Amount,+with ANSI colour codes disabled:++$ hledger test -- -pData.Amount --color=never++ For help on these, see https://github.com/feuerbach/tasty#options+(‘-- --help’ currently doesn’t show them).+++File: hledger.info, Node: PART 5 COMMON TASKS, Prev: PART 4 COMMANDS, Up: Top++25 PART 5: COMMON TASKS+***********************++Here are some quick examples of how to do some basic tasks with hledger.++* Menu:++* Getting help::+* Constructing command lines::+* Starting a journal file::+* Setting opening balances::+* Recording transactions::+* Reconciling::+* Reporting::+* Migrating to a new file::+++File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS++25.1 Getting help+=================++Here’s how to list commands and view options and command docs:++$ hledger # show available commands+$ hledger --help # show common options+$ hledger CMD --help # show CMD's options, common options and CMD's documentation++ You can also view your hledger version’s manual in several formats by+using the help command. Eg:++$ hledger help # show the hledger manual with info, man or $PAGER (best available)+$ hledger help journal # show the journal topic in the hledger manual+$ hledger help --help # find out more about the help command++ To view manuals and introductory docs on the web, visit+https://hledger.org. Chat and mail list support and discussion archives+can be found at https://hledger.org/support.+++File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS++25.2 Constructing command lines+===============================++hledger has a flexible command line interface. We strive to keep it+simple and ergonomic, but if you run into one of the sharp edges+described in OPTIONS, here are some tips that might help:++ • command-specific options must go after the command (it’s fine to+ put common options there too: ‘hledger CMD OPTS ARGS’)+ • running add-on executables directly simplifies command line parsing+ (‘hledger-ui OPTS ARGS’)+ • enclose "problematic" args in single quotes+ • if needed, also add a backslash to hide regular expression+ metacharacters from the shell+ • to see how a misbehaving command line is being parsed, add+ ‘--debug=2’.+++File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: PART 5 COMMON TASKS++25.3 Starting a journal file+============================++hledger looks for your accounting data in a journal file,+‘$HOME/.hledger.journal’ by default:++$ hledger stats+The hledger journal file "/Users/simon/.hledger.journal" was not found.+Please create it first, eg with "hledger add" or a text editor.+Or, specify an existing journal file with -f or LEDGER_FILE.++ You can override this by setting the ‘LEDGER_FILE’ environment+variable. It’s a good practice to keep this important file under+version control, and to start a new file each year. So you could do+something like this:++$ mkdir ~/finance+$ cd ~/finance+$ git init+Initialized empty Git repository in /Users/simon/finance/.git/+$ touch 2020.journal+$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc+$ source ~/.bashrc+$ hledger stats+Main file : /Users/simon/finance/2020.journal+Included files : +Transactions span : to (0 days)+Last transaction : none+Transactions : 0 (0.0 per day)+Transactions last 30 days: 0 (0.0 per day)+Transactions last 7 days : 0 (0.0 per day)+Payees/descriptions : 0+Accounts : 0 (depth 0)+Commodities : 0 ()+Market prices : 0 ()+++File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: PART 5 COMMON TASKS++25.4 Setting opening balances+=============================++Pick a starting date for which you can look up the balances of some+real-world assets (bank accounts, wallet..) and liabilities (credit+cards..).++ To avoid a lot of data entry, you may want to start with just one or+two accounts, like your checking account or cash wallet; and pick a+recent starting date, like today or the start of the week. You can+always come back later and add more accounts and older transactions, eg+going back to january 1st.++ Add an opening balances transaction to the journal, declaring the+balances on this date. Here are two ways to do it:++ • The first way: open the journal in any text editor and save an+ entry like this:++ 2020-01-01 * opening balances+ assets:bank:checking $1000 = $1000+ assets:bank:savings $2000 = $2000+ assets:cash $100 = $100+ liabilities:creditcard $-50 = $-50+ equity:opening/closing balances++ These are start-of-day balances, ie whatever was in the account at+ the end of the previous day.++ The * after the date is an optional status flag. Here it means+ "cleared & confirmed".++ The currency symbols are optional, but usually a good idea as+ you’ll be dealing with multiple currencies sooner or later.++ The = amounts are optional balance assertions, providing extra+ error checking.++ • The second way: run ‘hledger add’ and follow the prompts to record+ a similar transaction:++ $ hledger add+ Adding transactions to journal file /Users/simon/finance/2020.journal+ Any command line arguments will be used as defaults.+ Use tab key to complete, readline keys to edit, enter to accept defaults.+ An optional (CODE) may follow transaction dates.+ An optional ; COMMENT may follow descriptions or amounts.+ If you make a mistake, enter < at any prompt to go one step backward.+ To end a transaction, enter . when prompted.+ To quit, enter . at a date prompt or press control-d or control-c.+ Date [2020-02-07]: 2020-01-01+ Description: * opening balances+ Account 1: assets:bank:checking+ Amount 1: $1000+ Account 2: assets:bank:savings+ Amount 2 [$-1000]: $2000+ Account 3: assets:cash+ Amount 3 [$-3000]: $100+ Account 4: liabilities:creditcard+ Amount 4 [$-3100]: $-50+ Account 5: equity:opening/closing balances+ Amount 5 [$-3050]: + Account 6 (or . or enter to finish this transaction): .+ 2020-01-01 * opening balances+ assets:bank:checking $1000+ assets:bank:savings $2000+ assets:cash $100+ liabilities:creditcard $-50+ equity:opening/closing balances $-3050+ + Save this transaction to the journal ? [y]: + Saved.+ Starting the next transaction (. or ctrl-D/ctrl-C to quit)+ Date [2020-01-01]: .++ If you’re using version control, this could be a good time to commit+the journal. Eg:++$ git commit -m 'initial balances' 2020.journal+++File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS++25.5 Recording transactions+===========================++As you spend or receive money, you can record these transactions using+one of the methods above (text editor, hledger add) or by using the+hledger-iadd or hledger-web add-ons, or by using the import command to+convert CSV data downloaded from your bank.++ Here are some simple transactions, see the hledger_journal(5) manual+and hledger.org for more ideas:++2020/1/10 * gift received+ assets:cash $20+ income:gifts++2020.1.12 * farmers market+ expenses:food $13+ assets:cash++2020-01-15 paycheck+ income:salary+ assets:bank:checking $1000+++File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS++25.6 Reconciling+================++Periodically you should reconcile - compare your hledger-reported+balances against external sources of truth, like bank statements or your+bank’s website - to be sure that your ledger accurately represents the+real-world balances (and, that the real-world institutions have not made+a mistake!). This gets easy and fast with (1) practice and (2)+frequency. If you do it daily, it can take 2-10 minutes. If you let it+pile up, expect it to take longer as you hunt down errors and+discrepancies.++ A typical workflow:++ 1. Reconcile cash. Count what’s in your wallet. Compare with what+ hledger reports (‘hledger bal cash’). If they are different, try+ to remember the missing transaction, or look for the error in the+ already-recorded transactions. A register report can be helpful+ (‘hledger reg cash’). If you can’t find the error, add an+ adjustment transaction. Eg if you have $105 after the above, and+ can’t explain the missing $2, it could be:++ 2020-01-16 * adjust cash+ assets:cash $-2 = $105+ expenses:misc++ 2. Reconcile checking. Log in to your bank’s website. Compare+ today’s (cleared) balance with hledger’s cleared balance (‘hledger+ bal checking -C’). If they are different, track down the error or+ record the missing transaction(s) or add an adjustment transaction,+ similar to the above. Unlike the cash case, you can usually+ compare the transaction history and running balance from your bank+ with the one reported by ‘hledger reg checking -C’. This will be+ easier if you generally record transaction dates quite similar to+ your bank’s clearing dates.++ 3. Repeat for other asset/liability accounts.++ Tip: instead of the register command, use hledger-ui to see a+live-updating register while you edit the journal: ‘hledger-ui --watch+--register checking -C’++ After reconciling, it could be a good time to mark the reconciled+transactions’ status as "cleared and confirmed", if you want to track+that, by adding the ‘*’ marker. Eg in the paycheck transaction above,+insert ‘*’ between ‘2020-01-15’ and ‘paycheck’++ If you’re using version control, this can be another good time to+commit:++$ git commit -m 'txns' 2020.journal+++File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS++25.7 Reporting+==============++Here are some basic reports.++ Show all transactions:++$ hledger print+2020-01-01 * opening balances+ assets:bank:checking $1000+ assets:bank:savings $2000+ assets:cash $100+ liabilities:creditcard $-50+ equity:opening/closing balances $-3050++2020-01-10 * gift received+ assets:cash $20+ income:gifts++2020-01-12 * farmers market+ expenses:food $13+ assets:cash++2020-01-15 * paycheck+ income:salary+ assets:bank:checking $1000++2020-01-16 * adjust cash+ assets:cash $-2 = $105+ expenses:misc++ Show account names, and their hierarchy:++$ hledger accounts --tree+assets+ bank+ checking+ savings+ cash+equity+ opening/closing balances+expenses+ food+ misc+income+ gifts+ salary+liabilities+ creditcard++ Show all account totals:++$ hledger balance+ $4105 assets+ $4000 bank+ $2000 checking+ $2000 savings+ $105 cash+ $-3050 equity:opening/closing balances+ $15 expenses+ $13 food+ $2 misc+ $-1020 income+ $-20 gifts+ $-1000 salary+ $-50 liabilities:creditcard+--------------------+ 0++ Show only asset and liability balances, as a flat list, limited to+depth 2:++$ hledger bal assets liabilities -2+ $4000 assets:bank+ $105 assets:cash+ $-50 liabilities:creditcard+--------------------+ $4055++ Show the same thing without negative numbers, formatted as a simple+balance sheet:++$ hledger bs -2+Balance Sheet 2020-01-16++ || 2020-01-16 +========================++============+ Assets || +------------------------++------------+ assets:bank || $4000 + assets:cash || $105 +------------------------++------------+ || $4105 +========================++============+ Liabilities || +------------------------++------------+ liabilities:creditcard || $50 +------------------------++------------+ || $50 +========================++============+ Net: || $4055 ++ The final total is your "net worth" on the end date. (Or use ‘bse’+for a full balance sheet with equity.)++ Show income and expense totals, formatted as an income statement:++hledger is +Income Statement 2020-01-01-2020-01-16++ || 2020-01-01-2020-01-16 +===============++=======================+ Revenues || +---------------++-----------------------+ income:gifts || $20 + income:salary || $1000 +---------------++-----------------------+ || $1020 +===============++=======================+ Expenses || +---------------++-----------------------+ expenses:food || $13 + expenses:misc || $2 +---------------++-----------------------+ || $15 +===============++=======================+ Net: || $1005 ++ The final total is your net income during this period.++ Show transactions affecting your wallet, with running total:++$ hledger register cash+2020-01-01 opening balances assets:cash $100 $100+2020-01-10 gift received assets:cash $20 $120+2020-01-12 farmers market assets:cash $-13 $107+2020-01-16 adjust cash assets:cash $-2 $105++ Show weekly posting counts as a bar chart:++$ hledger activity -W+2019-12-30 *****+2020-01-06 ****+2020-01-13 ****+++File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS++25.8 Migrating to a new file+============================++At the end of the year, you may want to continue your journal in a new+file, so that old transactions don’t slow down or clutter your reports,+and to help ensure the integrity of your accounting history. See the+close command.++ If using version control, don’t forget to ‘git add’ the new file.+++Tag Table:+Node: Top210+Node: PART 1 USER INTERFACE3946+Ref: #part-1-user-interface4087+Node: Options4087+Ref: #options4206+Node: General options4348+Ref: #general-options4473+Node: Command options8923+Ref: #command-options9074+Node: Command arguments9490+Ref: #command-arguments9648+Node: Special characters10550+Ref: #special-characters10713+Node: Single escaping shell metacharacters10876+Ref: #single-escaping-shell-metacharacters11117+Node: Double escaping regular expression metacharacters11752+Ref: #double-escaping-regular-expression-metacharacters12063+Node: Triple escaping for add-on commands12633+Ref: #triple-escaping-for-add-on-commands12893+Node: Less escaping13561+Ref: #less-escaping13715+Node: Unicode characters14053+Ref: #unicode-characters14218+Node: Regular expressions15650+Ref: #regular-expressions15790+Node: Environment17644+Ref: #environment17755+Node: Input19366+Ref: #input19466+Node: Data formats20029+Ref: #data-formats20142+Node: Multiple files21594+Ref: #multiple-files21731+Node: Strict mode22216+Ref: #strict-mode22326+Node: Commands23080+Ref: #commands23181+Node: Add-on commands23665+Ref: #add-on-commands23767+Node: Output24934+Ref: #output25037+Node: Output destination25153+Ref: #output-destination25284+Node: Output format25713+Ref: #output-format25859+Node: CSV output27431+Ref: #csv-output27547+Node: HTML output27652+Ref: #html-output27790+Node: JSON output27890+Ref: #json-output28028+Node: SQL output28960+Ref: #sql-output29076+Node: Commodity styles29599+Ref: #commodity-styles29739+Node: Colour30346+Ref: #colour30464+Node: Box-drawing30898+Ref: #box-drawing31022+Node: Debug output31336+Ref: #debug-output31447+Node: Limitations32122+Ref: #limitations32242+Node: Troubleshooting33017+Ref: #troubleshooting33158+Node: PART 2 DATA FORMATS35680+Ref: #part-2-data-formats35827+Node: Journal35827+Ref: #journal35938+Node: Journal cheatsheet36581+Ref: #journal-cheatsheet36722+Node: About journal format40710+Ref: #about-journal-format40872+Node: Comments42410+Ref: #comments42542+Node: Transactions43396+Ref: #transactions43521+Node: Dates44555+Ref: #dates44664+Node: Simple dates44709+Ref: #simple-dates44827+Node: Posting dates45359+Ref: #posting-dates45479+Node: Status46462+Ref: #status46565+Node: Code48317+Ref: #code48422+Node: Description48654+Ref: #description48787+Node: Payee and note49109+Ref: #payee-and-note49217+Node: Transaction comments49564+Ref: #transaction-comments49719+Node: Postings50090+Ref: #postings50225+Node: Account names51234+Ref: #account-names51366+Node: Amounts53068+Ref: #amounts53185+Node: Decimal marks digit group marks54174+Ref: #decimal-marks-digit-group-marks54351+Node: Commodity55375+Ref: #commodity55564+Node: Directives influencing number parsing and display56546+Ref: #directives-influencing-number-parsing-and-display56807+Node: Commodity display style57269+Ref: #commodity-display-style57477+Node: Rounding59688+Ref: #rounding59808+Node: Costs60109+Ref: #costs60227+Node: Other cost/lot notations62258+Ref: #other-costlot-notations62392+Node: Balance assertions65145+Ref: #balance-assertions65298+Node: Assertions and ordering66391+Ref: #assertions-and-ordering66582+Node: Assertions and multiple included files67284+Ref: #assertions-and-multiple-included-files67546+Node: Assertions and multiple -f files68054+Ref: #assertions-and-multiple--f-files68307+Node: Assertions and commodities68716+Ref: #assertions-and-commodities68940+Node: Assertions and prices70130+Ref: #assertions-and-prices70338+Node: Assertions and subaccounts70769+Ref: #assertions-and-subaccounts70992+Node: Assertions and virtual postings71334+Ref: #assertions-and-virtual-postings71574+Node: Assertions and auto postings71714+Ref: #assertions-and-auto-postings71946+Node: Assertions and precision72617+Ref: #assertions-and-precision72801+Node: Posting comments73068+Ref: #posting-comments73216+Node: Tags73601+Ref: #tags73717+Node: Tag values74922+Ref: #tag-values75013+Node: Directives75786+Ref: #directives75915+Node: Directive effects77783+Ref: #directive-effects77939+Node: Directives and multiple files81022+Ref: #directives-and-multiple-files81202+Node: account directive81912+Ref: #account-directive82074+Node: Account comments83494+Ref: #account-comments83646+Node: Account subdirectives84166+Ref: #account-subdirectives84359+Node: Account error checking84501+Ref: #account-error-checking84701+Node: Account display order85920+Ref: #account-display-order86110+Node: Account types87249+Ref: #account-types87392+Node: alias directive91127+Ref: #alias-directive91294+Node: Basic aliases92354+Ref: #basic-aliases92487+Node: Regex aliases93241+Ref: #regex-aliases93400+Node: Combining aliases94294+Ref: #combining-aliases94474+Node: Aliases and multiple files95768+Ref: #aliases-and-multiple-files95974+Node: end aliases directive96559+Ref: #end-aliases-directive96784+Node: Aliases can generate bad account names96933+Ref: #aliases-can-generate-bad-account-names97183+Node: Aliases and account types97780+Ref: #aliases-and-account-types97974+Node: commodity directive98676+Ref: #commodity-directive98856+Node: Commodity error checking101460+Ref: #commodity-error-checking101608+Node: decimal-mark directive102137+Ref: #decimal-mark-directive102325+Node: include directive102726+Ref: #include-directive102896+Node: P directive103844+Ref: #p-directive103995+Node: payee directive104894+Ref: #payee-directive105049+Node: tag directive105369+Ref: #tag-directive105530+Node: Periodic transactions106002+Ref: #periodic-transactions106168+Node: Periodic rule syntax107906+Ref: #periodic-rule-syntax108086+Node: Periodic rules and relative dates108741+Ref: #periodic-rules-and-relative-dates109009+Node: Two spaces between period expression and description!109548+Ref: #two-spaces-between-period-expression-and-description109827+Node: Other syntax110517+Ref: #other-syntax110643+Node: Auto postings111288+Ref: #auto-postings111424+Node: Auto postings and multiple files113935+Ref: #auto-postings-and-multiple-files114137+Node: Auto postings and dates114354+Ref: #auto-postings-and-dates114626+Node: Auto postings and transaction balancing / inferred amounts / balance assertions114801+Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions115140+Node: Auto posting tags115647+Ref: #auto-posting-tags115860+Node: Balance assignments116522+Ref: #balance-assignments116702+Node: Balance assignments and prices118036+Ref: #balance-assignments-and-prices118206+Node: Bracketed posting dates118417+Ref: #bracketed-posting-dates118603+Node: D directive119147+Ref: #d-directive119321+Node: apply account directive120989+Ref: #apply-account-directive121175+Node: Y directive121874+Ref: #y-directive122040+Node: Secondary dates122884+Ref: #secondary-dates123040+Node: Star comments123872+Ref: #star-comments124034+Node: Valuation expressions124574+Ref: #valuation-expressions124753+Node: Virtual postings124875+Ref: #virtual-postings125056+Node: Other Ledger directives126628+Ref: #other-ledger-directives126793+Node: CSV127363+Ref: #csv127456+Node: CSV rules cheatsheet129559+Ref: #csv-rules-cheatsheet129691+Node: separator131459+Ref: #separator131590+Node: skip132168+Ref: #skip132280+Node: date-format132863+Ref: #date-format132988+Node: timezone133734+Ref: #timezone133861+Node: newest-first134894+Ref: #newest-first135036+Node: intra-day-reversed135620+Ref: #intra-day-reversed135778+Node: decimal-mark136275+Ref: #decimal-mark136420+Node: fields list136759+Ref: #fields-list136900+Node: Field assignment138623+Ref: #field-assignment138767+Node: Field names139816+Ref: #field-names139947+Node: date field141168+Ref: #date-field141286+Node: date2 field141338+Ref: #date2-field141479+Node: status field141541+Ref: #status-field141684+Node: code field141739+Ref: #code-field141884+Node: description field141935+Ref: #description-field142095+Node: comment field142160+Ref: #comment-field142315+Node: account field142628+Ref: #account-field142778+Node: amount field143374+Ref: #amount-field143523+Node: currency field145628+Ref: #currency-field145781+Node: balance field146050+Ref: #balance-field146182+Node: if block146570+Ref: #if-block146695+Node: Matchers148119+Ref: #matchers148233+Node: if table149763+Ref: #if-table149889+Node: balance-type151325+Ref: #balance-type151458+Node: include152166+Ref: #include152297+Node: Working with CSV152747+Ref: #working-with-csv152894+Node: Rapid feedback153265+Ref: #rapid-feedback153398+Node: Valid CSV153854+Ref: #valid-csv154000+Node: File Extension154754+Ref: #file-extension154927+Node: Reading CSV from standard input155517+Ref: #reading-csv-from-standard-input155741+Node: Reading multiple CSV files155907+Ref: #reading-multiple-csv-files156125+Node: Valid transactions156374+Ref: #valid-transactions156568+Node: Deduplicating importing157196+Ref: #deduplicating-importing157391+Node: Setting amounts158437+Ref: #setting-amounts158608+Node: Amount signs161131+Ref: #amount-signs161299+Node: Setting currency/commodity162038+Ref: #setting-currencycommodity162242+Node: Amount decimal places163434+Ref: #amount-decimal-places163640+Node: Referencing other fields163958+Ref: #referencing-other-fields164171+Node: How CSV rules are evaluated165074+Ref: #how-csv-rules-are-evaluated165291+Node: Well factored rules166804+Ref: #well-factored-rules166972+Node: CSV rules examples167310+Ref: #csv-rules-examples167445+Node: Bank of Ireland167510+Ref: #bank-of-ireland167647+Node: Coinbase169115+Ref: #coinbase169253+Node: Amazon170306+Ref: #amazon170431+Node: Paypal172156+Ref: #paypal172264+Node: Timeclock179910+Ref: #timeclock180015+Node: Timedot182183+Ref: #timedot182306+Node: PART 3 REPORTING CONCEPTS187157+Ref: #part-3-reporting-concepts187321+Node: Time periods187321+Ref: #time-periods187455+Node: Report start & end date187573+Ref: #report-start-end-date187725+Node: Smart dates189458+Ref: #smart-dates189611+Node: Report intervals191571+Ref: #report-intervals191726+Node: Date adjustment192178+Ref: #date-adjustment192338+Node: Period expressions193670+Ref: #period-expressions193811+Node: Period expressions with a report interval195647+Ref: #period-expressions-with-a-report-interval195881+Node: More complex report intervals196111+Ref: #more-complex-report-intervals196356+Node: Multiple weekday intervals198285+Ref: #multiple-weekday-intervals198474+Node: Depth199338+Ref: #depth199440+Node: Queries199760+Ref: #queries199862+Node: Query types200807+Ref: #query-types200928+Node: Combining query terms204268+Ref: #combining-query-terms204445+Node: Queries and command options205543+Ref: #queries-and-command-options205742+Node: Queries and valuation206007+Ref: #queries-and-valuation206202+Node: Querying with account aliases206441+Ref: #querying-with-account-aliases206652+Node: Querying with cost or value206794+Ref: #querying-with-cost-or-value206971+Node: Pivoting207280+Ref: #pivoting207394+Node: Generating data208882+Ref: #generating-data209014+Node: Forecasting209512+Ref: #forecasting209637+Node: Budgeting212524+Ref: #budgeting212644+Node: Cost reporting212915+Ref: #cost-reporting213043+Node: -B Convert to cost214158+Ref: #b-convert-to-cost214314+Node: Equity conversion postings215722+Ref: #equity-conversion-postings215936+Node: Inferring equity postings from cost216831+Ref: #inferring-equity-postings-from-cost217080+Node: Inferring cost from equity postings217899+Ref: #inferring-cost-from-equity-postings218147+Node: When to infer cost/equity219956+Ref: #when-to-infer-costequity220174+Node: How to record conversions220582+Ref: #how-to-record-conversions220774+Node: Conversion with implicit cost221065+Ref: #conversion-with-implicit-cost221270+Node: Conversion with explicit cost222175+Ref: #conversion-with-explicit-cost222420+Node: Conversion with equity postings222847+Ref: #conversion-with-equity-postings223116+Node: Conversion with equity postings and explicit cost223953+Ref: #conversion-with-equity-postings-and-explicit-cost224220+Node: Cost tips224694+Ref: #cost-tips224820+Node: Valuation225556+Ref: #valuation225680+Node: -V Value226466+Ref: #v-value226592+Node: -X Value in specified commodity226791+Ref: #x-value-in-specified-commodity226986+Node: Valuation date227143+Ref: #valuation-date227314+Node: Finding market price227753+Ref: #finding-market-price227958+Node: --infer-market-prices market prices from transactions229138+Ref: #infer-market-prices-market-prices-from-transactions229416+Node: Valuation commodity232262+Ref: #valuation-commodity232475+Node: Simple valuation examples233720+Ref: #simple-valuation-examples233918+Node: --value Flexible valuation234581+Ref: #value-flexible-valuation234787+Node: More valuation examples236473+Ref: #more-valuation-examples236682+Node: Interaction of valuation and queries238693+Ref: #interaction-of-valuation-and-queries238934+Node: Effect of valuation on reports239414+Ref: #effect-of-valuation-on-reports239611+Node: PART 4 COMMANDS247370+Ref: #part-4-commands247513+Node: Commands overview247883+Ref: #commands-overview248017+Node: DATA ENTRY248196+Ref: #data-entry248320+Node: DATA CREATION248523+Ref: #data-creation248677+Node: DATA MANAGEMENT248801+Ref: #data-management248966+Node: REPORTS FINANCIAL249091+Ref: #reports-financial249266+Node: REPORTS VERSATILE249581+Ref: #reports-versatile249754+Node: REPORTS BASIC250015+Ref: #reports-basic250167+Node: HELP250700+Ref: #help250822+Node: ADD-ONS250881+Ref: #add-ons250987+Node: accounts251584+Ref: #accounts251717+Node: activity253692+Ref: #activity253811+Node: add254185+Ref: #add254295+Node: aregister257156+Ref: #aregister257277+Node: aregister and custom posting dates260253+Ref: #aregister-and-custom-posting-dates260419+Node: balance260987+Ref: #balance261113+Node: balance features262118+Ref: #balance-features262258+Node: Simple balance report264388+Ref: #simple-balance-report264573+Node: Balance report line format266218+Ref: #balance-report-line-format266420+Node: Filtered balance report268670+Ref: #filtered-balance-report268862+Node: List or tree mode269189+Ref: #list-or-tree-mode269357+Node: Depth limiting270732+Ref: #depth-limiting270898+Node: Dropping top-level accounts271515+Ref: #dropping-top-level-accounts271715+Node: Showing declared accounts272029+Ref: #showing-declared-accounts272228+Node: Sorting by amount272769+Ref: #sorting-by-amount272936+Node: Percentages273626+Ref: #percentages273785+Node: Multi-period balance report274355+Ref: #multi-period-balance-report274555+Node: Balance change end balance276948+Ref: #balance-change-end-balance277157+Node: Balance report types278605+Ref: #balance-report-types278786+Node: Calculation type279302+Ref: #calculation-type279457+Node: Accumulation type279988+Ref: #accumulation-type280168+Node: Valuation type281096+Ref: #valuation-type281284+Node: Combining balance report types282351+Ref: #combining-balance-report-types282545+Node: Budget report284449+Ref: #budget-report284601+Node: Budget report start date290335+Ref: #budget-report-start-date290513+Node: Budgets and subaccounts291875+Ref: #budgets-and-subaccounts292082+Node: Selecting budget goals295568+Ref: #selecting-budget-goals295767+Node: Budget vs forecast296814+Ref: #budget-vs-forecast296973+Node: Data layout298673+Ref: #data-layout298823+Node: Useful balance reports306764+Ref: #useful-balance-reports306914+Node: balancesheet308067+Ref: #balancesheet308212+Node: balancesheetequity309578+Ref: #balancesheetequity309736+Node: cashflow311179+Ref: #cashflow311310+Node: check312796+Ref: #check312910+Node: Basic checks313716+Ref: #basic-checks313836+Node: Strict checks314374+Ref: #strict-checks314517+Node: Other checks314958+Ref: #other-checks315100+Node: Custom checks315677+Ref: #custom-checks315834+Node: More about specific checks316255+Ref: #more-about-specific-checks316417+Node: close317149+Ref: #close317260+Node: close and costs319898+Ref: #close-and-costs320042+Node: close and balance assertions320331+Ref: #close-and-balance-assertions320533+Node: Example retain earnings321704+Ref: #example-retain-earnings321921+Node: Example migrate balances to a new file322279+Ref: #example-migrate-balances-to-a-new-file322544+Node: Example excluding closing/opening transactions323097+Ref: #example-excluding-closingopening-transactions323346+Node: codes324524+Ref: #codes324641+Node: commodities325517+Ref: #commodities325653+Node: descriptions325723+Ref: #descriptions325860+Node: diff326151+Ref: #diff326266+Node: files327312+Ref: #files327421+Node: help327562+Ref: #help-1327671+Node: import328661+Ref: #import328784+Node: Deduplication329892+Ref: #deduplication330017+Node: Import testing331939+Ref: #import-testing332104+Node: Importing balance assignments332955+Ref: #importing-balance-assignments333161+Node: Commodity display styles333818+Ref: #commodity-display-styles333991+Node: incomestatement334120+Ref: #incomestatement334262+Node: notes335629+Ref: #notes335751+Node: payees336113+Ref: #payees336228+Node: prices336753+Ref: #prices336868+Node: print337170+Ref: #print337285+Node: register342731+Ref: #register342853+Node: Custom register output347962+Ref: #custom-register-output348093+Node: rewrite349468+Ref: #rewrite349586+Node: Re-write rules in a file351498+Ref: #re-write-rules-in-a-file351661+Node: Diff output format352814+Ref: #diff-output-format352997+Node: rewrite vs print --auto354109+Ref: #rewrite-vs.-print---auto354271+Node: roi354845+Ref: #roi354952+Node: Spaces and special characters in --inv and --pnl356713+Ref: #spaces-and-special-characters-in---inv-and---pnl356961+Node: Semantics of --inv and --pnl357459+Ref: #semantics-of---inv-and---pnl357706+Node: IRR and TWR explained359584+Ref: #irr-and-twr-explained359744+Node: stats362856+Ref: #stats362964+Node: tags364361+Ref: #tags-1364468+Node: test365485+Ref: #test365578+Node: PART 5 COMMON TASKS366328+Ref: #part-5-common-tasks366461+Node: Getting help366735+Ref: #getting-help366876+Node: Constructing command lines367640+Ref: #constructing-command-lines367841+Node: Starting a journal file368522+Ref: #starting-a-journal-file368729+Node: Setting opening balances369927+Ref: #setting-opening-balances370132+Node: Recording transactions373285+Ref: #recording-transactions373474+Node: Reconciling374030+Ref: #reconciling374182+Node: Reporting376495+Ref: #reporting376644+Node: Migrating to a new file380633+Ref: #migrating-to-a-new-file380790 End Tag Table
embeddedfiles/hledger.txt view
@@ -18,8 +18,8 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.29. It- also describes the common options, file formats and concepts used by+ This manual is for hledger's command line interface, version 1.29.1.+ It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeep- ing/accounting as well! You don't need to know everything in here to use hledger productively, but when you have a question about function-@@ -8659,4 +8659,4 @@ -hledger-1.29 March 2023 HLEDGER(1)+hledger-1.29.1 March 2023 HLEDGER(1)
hledger.1 view
@@ -1,6 +1,6 @@ .\"t -.TH "HLEDGER" "1" "March 2023" "hledger-1.29 " "hledger User Manuals"+.TH "HLEDGER" "1" "March 2023" "hledger-1.29.1 " "hledger User Manuals" @@ -26,7 +26,7 @@ hledger is inspired by and largely compatible with ledger(1), and largely interconvertible with beancount(1). .PP-This manual is for hledger\[aq]s command line interface, version 1.29.+This manual is for hledger\[aq]s command line interface, version 1.29.1. It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeeping/accounting as well!
hledger.cabal view
@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack name: hledger-version: 1.29+version: 1.29.1 synopsis: Command-line interface for the hledger accounting system description: The command-line interface for the hledger accounting system. Its basic function is to read a plain text file describing@@ -131,13 +131,13 @@ other-modules: Paths_hledger ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path- cpp-options: -DVERSION="1.29"+ cpp-options: -DVERSION="1.29.1" build-depends: Decimal >=0.5.1 , Diff >=0.2 , aeson >=1 , ansi-terminal >=0.9- , base >=4.14 && <4.18+ , base >=4.14 && <4.19 , bytestring , cmdargs >=0.10 , containers >=0.5.9@@ -148,7 +148,7 @@ , githash >=0.1.6.2 , hashable >=1.2.4 , haskeline >=0.6- , hledger-lib ==1.29.*+ , hledger-lib >=1.29.1 && <1.30 , lucid , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.4@@ -183,12 +183,12 @@ hs-source-dirs: app ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path- cpp-options: -DVERSION="1.29"+ cpp-options: -DVERSION="1.29.1" build-depends: Decimal >=0.5.1 , aeson >=1 , ansi-terminal >=0.9- , base >=4.14 && <4.18+ , base >=4.14 && <4.19 , bytestring , cmdargs >=0.10 , containers >=0.5.9@@ -199,7 +199,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger- , hledger-lib ==1.29.*+ , hledger-lib >=1.29.1 && <1.30 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.4 , microlens >=0.4@@ -234,12 +234,12 @@ hs-source-dirs: test ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path- cpp-options: -DVERSION="1.29"+ cpp-options: -DVERSION="1.29.1" build-depends: Decimal >=0.5.1 , aeson >=1 , ansi-terminal >=0.9- , base >=4.14 && <4.18+ , base >=4.14 && <4.19 , bytestring , cmdargs >=0.10 , containers >=0.5.9@@ -250,7 +250,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger- , hledger-lib ==1.29.*+ , hledger-lib >=1.29.1 && <1.30 , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.4 , microlens >=0.4@@ -287,7 +287,7 @@ Decimal >=0.5.1 , aeson >=1 , ansi-terminal >=0.9- , base >=4.14 && <4.18+ , base >=4.14 && <4.19 , bytestring , cmdargs >=0.10 , containers >=0.5.9@@ -299,7 +299,7 @@ , githash >=0.1.6.2 , haskeline >=0.6 , hledger- , hledger-lib ==1.29.*+ , hledger-lib >=1.29.1 && <1.30 , html , math-functions >=0.3.3.0 , megaparsec >=7.0.0 && <9.4
hledger.info view
@@ -23,10948 +23,10948 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger’s command line interface, version 1.29.-It also describes the common options, file formats and concepts used by-all hledger programs. It might accidentally teach you some-bookkeeping/accounting as well! You don’t need to know everything in-here to use hledger productively, but when you have a question about-functionality, this doc should answer it. It is detailed, so do skip-ahead or skim when needed. You can read it on hledger.org, or as an-info manual or man page on your system. You can also get it from-hledger itself with-‘hledger --man’, ‘hledger --info’ or ‘hledger help [TOPIC]’.-- The main function of the hledger CLI is to read plain text files-describing financial transactions, crunch the numbers, and print a-useful report on the terminal (or save it as HTML, CSV, JSON or SQL).-Many reports are available, as subcommands. hledger will also detect-other ‘hledger-*’ executables as extra subcommands.-- hledger reads data from one or more files in journal, timeclock,-timedot, or CSV format. The default file is ‘.hledger.journal’ in your-home directory; this can be overridden with one or more ‘-f FILE’-options, or the ‘LEDGER_FILE’ environment variable. hledger CLI can-also read from stdin with ‘-f-’; more on that below.-- Here is a small but valid hledger journal file describing one-transaction:--2015-10-16 bought food- expenses:food $10- assets:cash-- Transactions are dated movements of money (etc.) between two or more-_accounts_: bank accounts, your wallet, revenue/expense categories,-people, etc. You can choose any account names you wish, using ‘:’ to-indicate subaccounts. There must be at least two spaces between account-name and amount. Positive amounts are inflow to that account (_debit_),-negatives are outflow from it (_credit_). (Some reports show revenue,-liability and equity account balances as negative numbers as a result;-this is normal.)-- hledger’s add command can help you add transactions, or you can-install other data entry UIs like hledger-web or hledger-iadd. For more-extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM-+ vim-ledger, or VS Code + hledger-vscode are some good choices (see-https://hledger.org/editors.html).-- To get started, run ‘hledger add’ and follow the prompts, or save-some entries like the above in ‘$HOME/.hledger.journal’, then try-commands like:-‘hledger print -x’-‘hledger aregister assets’-‘hledger balance’-‘hledger balancesheet’-‘hledger incomestatement’.-Run ‘hledger’ to list the commands. See also the "Starting a journal-file" and "Setting opening balances" sections in PART 5: COMMON TASKS.--* Menu:--* PART 1 USER INTERFACE::-* Options::-* Environment::-* Input::-* Commands::-* Output::-* Limitations::-* Troubleshooting::-* PART 2 DATA FORMATS::-* Journal::-* CSV::-* Timeclock::-* Timedot::-* PART 3 REPORTING CONCEPTS::-* Time periods::-* Depth::-* Queries::-* Pivoting::-* Generating data::-* Forecasting::-* Budgeting::-* Cost reporting::-* Valuation::-* PART 4 COMMANDS::-* PART 5 COMMON TASKS::---File: hledger.info, Node: PART 1 USER INTERFACE, Next: Options, Prev: Top, Up: Top--1 PART 1: USER INTERFACE-************************---File: hledger.info, Node: Options, Next: Environment, Prev: PART 1 USER INTERFACE, Up: Top--2 Options-*********--* Menu:--* General options::-* Command options::-* Command arguments::-* Special characters::-* Unicode characters::-* Regular expressions::---File: hledger.info, Node: General options, Next: Command options, Up: Options--2.1 General options-===================--To see general usage help, including general options which are supported-by most hledger commands, run ‘hledger -h’.-- General help options:--‘-h --help’-- show general or COMMAND help-‘--man’-- show general or COMMAND user manual with man-‘--info’-- show general or COMMAND user manual with info-‘--version’-- show general or ADDONCMD version-‘--debug[=N]’-- show debug output (levels 1-9, default: 1)-- General input options:--‘-f FILE --file=FILE’-- use a different input file. For stdin, use - (default:- ‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’)-‘--rules-file=RULESFILE’-- Conversion rules file to use when reading CSV (default: FILE.rules)-‘--separator=CHAR’-- Field separator to expect when reading CSV (default: ’,’)-‘--alias=OLD=NEW’-- rename accounts named OLD to NEW-‘--anon’-- anonymize accounts and payees-‘--pivot FIELDNAME’-- use some other field or tag for the account name-‘-I --ignore-assertions’-- disable balance assertion checks (note: does not disable balance- assignments)-‘-s --strict’-- do extra error checking (check that all posted accounts are- declared)-- General reporting options:--‘-b --begin=DATE’-- include postings/txns on or after this date (will be adjusted to- preceding subperiod start when using a report interval)-‘-e --end=DATE’-- include postings/txns before this date (will be adjusted to- following subperiod end when using a report interval)-‘-D --daily’-- multiperiod/multicolumn report by day-‘-W --weekly’-- multiperiod/multicolumn report by week-‘-M --monthly’-- multiperiod/multicolumn report by month-‘-Q --quarterly’-- multiperiod/multicolumn report by quarter-‘-Y --yearly’-- multiperiod/multicolumn report by year-‘-p --period=PERIODEXP’-- set start date, end date, and/or reporting interval all at once- using period expressions syntax-‘--date2’-- match the secondary date instead (see command help for other- effects)-‘--today=DATE’-- override today’s date (affects relative smart dates, for- tests/examples)-‘-U --unmarked’-- include only unmarked postings/txns (can combine with -P or -C)-‘-P --pending’-- include only pending postings/txns-‘-C --cleared’-- include only cleared postings/txns-‘-R --real’-- include only non-virtual postings-‘-NUM --depth=NUM’-- hide/aggregate accounts or postings more than NUM levels deep-‘-E --empty’-- show items with zero amount, normally hidden (and vice-versa in- hledger-ui/hledger-web)-‘-B --cost’-- convert amounts to their cost/selling amount at transaction time-‘-V --market’-- convert amounts to their market value in default valuation- commodities-‘-X --exchange=COMM’-- convert amounts to their market value in commodity COMM-‘--value’-- convert amounts to cost or market value, more flexibly than- -B/-V/-X-‘--infer-market-prices’-- use transaction prices (recorded with @ or @@) as additional market- prices, as if they were P directives-‘--auto’-- apply automated posting rules to modify transactions.-‘--forecast’-- generate future transactions from periodic transaction rules, for- the next 6 months or till report end date. In hledger-ui, also- make ordinary future transactions visible.-‘--commodity-style’-- Override the commodity style in the output for the specified- commodity. For example ’EUR1.000,00’.-‘--color=WHEN (or --colour=WHEN)’-- Should color-supporting commands use ANSI color codes in text- output. ’auto’ (default): whenever stdout seems to be a- color-supporting terminal. ’always’ or ’yes’: always, useful eg- when piping output into ’less -R’. ’never’ or ’no’: never. A- NO_COLOR environment variable overrides this.-‘--pretty[=WHEN]’-- Show prettier output, e.g. using unicode box-drawing characters.- Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’- also work). If you provide an argument you must use ’=’, e.g.- ’–pretty=yes’.-- When a reporting option appears more than once in the command line,-the last one takes precedence.-- Some reporting options can also be written as query arguments.---File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: Options--2.2 Command options-===================--To see options for a particular command, including command-specific-options, run: ‘hledger COMMAND -h’.-- Command-specific options must be written after the command name, eg:-‘hledger print -x’.-- Additionally, if the command is an add-on, you may need to put its-options after a double-hyphen, eg: ‘hledger ui -- --watch’. Or, you can-run the add-on executable directly: ‘hledger-ui --watch’.---File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: Options--2.3 Command arguments-=====================--Most hledger commands accept arguments after the command name, which are-often a query, filtering the data in some way.-- You can save a set of command line options/arguments in a file, and-then reuse them by writing ‘@FILENAME’ as a command line argument. Eg:-‘hledger bal @foo.args’. (To prevent this, eg if you have an argument-that begins with a literal ‘@’, precede it with ‘--’, eg: ‘hledger bal--- @ARG’).-- Inside the argument file, each line should contain just one option or-argument. Avoid the use of spaces, except inside quotes (or you’ll see-a confusing error). Between a flag and its argument, use = (or-nothing). Bad:--assets depth:2--X USD-- Good:--assets-depth:2--X=USD-- For special characters (see below), use one less level of quoting-than you would at the command prompt. Bad:---X"$"-- Good:---X$-- See also: Save frequently used options.---File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: Options--2.4 Special characters-======================--* Menu:--* Single escaping shell metacharacters::-* Double escaping regular expression metacharacters::-* Triple escaping for add-on commands::-* Less escaping::---File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters--2.4.1 Single escaping (shell metacharacters)-----------------------------------------------In shell command lines, characters significant to your shell - such as-spaces, ‘<’, ‘>’, ‘(’, ‘)’, ‘|’, ‘$’ and ‘\’ - should be "shell-escaped"-if you want hledger to see them. This is done by enclosing them in-single or double quotes, or by writing a backslash before them. Eg to-match an account name containing a space:--$ hledger register 'credit card'-- or:--$ hledger register credit\ card-- Windows users should keep in mind that ‘cmd’ treats single quote as a-regular character, so you should be using double quotes exclusively.-PowerShell treats both single and double quotes as quotes.---File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters--2.4.2 Double escaping (regular expression metacharacters)------------------------------------------------------------Characters significant in regular expressions (described below) - such-as ‘.’, ‘^’, ‘$’, ‘[’, ‘]’, ‘(’, ‘)’, ‘|’, and ‘\’ - may need to be-"regex-escaped" if you don’t want them to be interpreted by hledger’s-regular expression engine. This is done by writing backslashes before-them, but since backslash is typically also a shell metacharacter, both-shell-escaping and regex-escaping will be needed. Eg to match a literal-‘$’ sign while using the bash shell:--$ hledger balance cur:'\$'-- or:--$ hledger balance cur:\\$---File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters--2.4.3 Triple escaping (for add-on commands)----------------------------------------------When you use hledger to run an external add-on command (described-below), one level of shell-escaping is lost from any options or-arguments intended for by the add-on command, so those need an extra-level of shell-escaping. Eg to match a literal ‘$’ sign while using the-bash shell and running an add-on command (‘ui’):--$ hledger ui cur:'\\$'-- or:--$ hledger ui cur:\\\\$-- If you wondered why _four_ backslashes, perhaps this helps:--unescaped: ‘$’-escaped: ‘\$’-double-escaped: ‘\\$’-triple-escaped: ‘\\\\$’-- Or, you can avoid the extra escaping by running the add-on executable-directly:--$ hledger-ui cur:\\$---File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters--2.4.4 Less escaping----------------------Options and arguments are sometimes used in places other than the shell-command line, where shell-escaping is not needed, so there you should-use one less level of escaping. Those places include:-- • an @argumentfile- • hledger-ui’s filter field- • hledger-web’s search form- • GHCI’s prompt (used by developers).---File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options--2.5 Unicode characters-======================--hledger is expected to handle non-ascii characters correctly:-- • they should be parsed correctly in input files and on the command- line, by all hledger tools (add, iadd, hledger-web’s- search/add/edit forms, etc.)-- • they should be displayed correctly by all hledger tools, and- on-screen alignment should be preserved.-- This requires a well-configured environment. Here are some tips:-- • A system locale must be configured, and it must be one that can- decode the characters being used. In bash, you can set a locale- like this: ‘export LANG=en_US.UTF-8’. There are some more details- in Troubleshooting. This step is essential - without it, hledger- will quit on encountering a non-ascii character (as with all- GHC-compiled programs).-- • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)- must support unicode-- • the terminal must be using a font which includes the required- unicode glyphs-- • the terminal should be configured to display wide characters as- double width (for report alignment)-- • on Windows, for best results you should run hledger in the same- kind of environment in which it was built. Eg hledger built in the- standard CMD.EXE environment (like the binaries on our download- page) might show display problems when run in a cygwin or msys- terminal, and vice versa. (See eg #961).---File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: Options--2.6 Regular expressions-=======================--hledger uses regular expressions in a number of places:-- • query terms, on the command line and in the hledger-web search- form: ‘REGEX’, ‘desc:REGEX’, ‘cur:REGEX’, ‘tag:...=REGEX’- • CSV rules conditional blocks: ‘if REGEX ...’- • account alias directive and ‘--alias’ option: ‘alias /REGEX/ =- REPLACEMENT’, ‘--alias /REGEX/=REPLACEMENT’-- hledger’s regular expressions come from the regex-tdfa library. If-they’re not doing what you expect, it’s important to know exactly what-they support:-- 1. they are case insensitive- 2. they are infix matching (they do not need to match the entire thing- being matched)- 3. they are POSIX ERE (extended regular expressions)- 4. they also support GNU word boundaries (‘\b’, ‘\B’, ‘\<’, ‘\>’)- 5. they do not support backreferences; if you write ‘\1’, it will- match the digit ‘1’. Except when doing text replacement, eg in- account aliases, where backreferences can be used in the- replacement string to reference capturing groups in the search- regexp.- 6. they do not support mode modifiers (‘(?s)’), character classes- (‘\w’, ‘\d’), or anything else not mentioned above.-- Some things to note:-- • In the ‘alias’ directive and ‘--alias’ option, regular expressions- must be enclosed in forward slashes (‘/REGEX/’). Elsewhere in- hledger, these are not required.-- • In queries, to match a regular expression metacharacter like ‘$’ as- a literal character, prepend a backslash. Eg to search for amounts- with the dollar sign in hledger-web, write ‘cur:\$’.-- • On the command line, some metacharacters like ‘$’ have a special- meaning to the shell and so must be escaped at least once more.- See Special characters.---File: hledger.info, Node: Environment, Next: Input, Prev: Options, Up: Top--3 Environment-*************--*LEDGER_FILE* The journal file path when not specified with ‘-f’.-- On unix computers, the default value is: ‘~/.hledger.journal’.-- A more typical value is something like ‘~/finance/YYYY.journal’,-where ‘~/finance’ is a version-controlled finance directory and YYYY is-the current year. Or, ‘~/finance/current.journal’, where-current.journal is a symbolic link to YYYY.journal.-- The usual way to set this permanently is to add a command to one of-your shell’s startup files (eg ‘~/.profile’):--export LEDGER_FILE=~/finance/current.journal`-- On some Mac computers, there is a more thorough way to set-environment variables, that will also affect applications started from-the GUI (eg, Emacs started from a dock icon): In-‘~/.MacOSX/environment.plist’, add an entry like:--{- "LEDGER_FILE" : "~/finance/current.journal"-}-- For this to take effect you might need to ‘killall Dock’, or reboot.-- On Windows computers, the default value is probably-‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a-command like this in a powershell window (let us know if you need to be-an Administrator, and if this persists across a reboot):--> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"-- Or, change it in settings: see-https://www.java.com/en/download/help/path.html.-- *COLUMNS* The screen width used by the register command. Default:-the full terminal width.-- *NO_COLOR* If this variable exists with any value, hledger will not-use ANSI color codes in terminal output. This is overriden by the-–color/–colour option.---File: hledger.info, Node: Input, Next: Commands, Prev: Environment, Up: Top--4 Input-*******--hledger reads transactions from one or more data files. The default-data file is ‘$HOME/.hledger.journal’ (or on Windows, something like-‘C:\Users\YOURNAME\.hledger.journal’).-- You can override this with the ‘$LEDGER_FILE’ environment variable:--$ setenv LEDGER_FILE ~/finance/2016.journal-$ hledger stats-- or with one or more ‘-f/--file’ options:--$ hledger -f /some/file -f another_file stats-- The file name ‘-’ means standard input:--$ cat some.journal | hledger -f---* Menu:--* Data formats::-* Multiple files::-* Strict mode::---File: hledger.info, Node: Data formats, Next: Multiple files, Up: Input--4.1 Data formats-================--Usually the data file is in hledger’s journal format, but it can be in-any of the supported file formats, which currently are:--Reader: Reads: Used for file- extensions:----------------------------------------------------------------------------‘journal’hledger journal files and some Ledger ‘.journal’ ‘.j’- journals, for transactions ‘.hledger’ ‘.ledger’-‘timeclock’timeclock files, for precise time ‘.timeclock’- logging-‘timedot’timedot files, for approximate time ‘.timedot’- logging-‘csv’ comma/semicolon/tab/other-separated ‘.csv’ ‘.ssv’ ‘.tsv’- values, for data import-- These formats are described in more detail below.-- hledger detects the format automatically based on the file extensions-shown above. If it can’t recognise the file extension, it assumes-‘journal’ format. So for non-journal files, it’s important to use a-recognised file extension, so as to either read successfully or to show-relevant error messages.-- You can also force a specific reader/format by prefixing the file-path with the format and a colon. Eg, to read a .dat file as csv-format:--$ hledger -f csv:/some/csv-file.dat stats-- Or to read stdin (‘-’) as timeclock format:--$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:----File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Data formats, Up: Input--4.2 Multiple files-==================--You can specify multiple ‘-f’ options, to read multiple files as one big-journal. There are some limitations with this:-- • most directives do not affect sibling files- • balance assertions will not see any account balances from previous- files-- If you need either of those things, you can-- • use a single parent file which includes the others- • or concatenate the files into one before reading, eg: ‘cat- a.journal b.journal | hledger -f- CMD’.---File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input--4.3 Strict mode-===============--hledger checks input files for valid data. By default, the most-important errors are detected, while still accepting easy journal files-without a lot of declarations:-- • Are the input files parseable, with valid syntax ?- • Are all transactions balanced ?- • Do all balance assertions pass ?-- With the ‘-s’/‘--strict’ flag, additional checks are performed:-- • Are all accounts posted to, declared with an ‘account’ directive ?- (Account error checking)- • Are all commodities declared with a ‘commodity’ directive ?- (Commodity error checking)- • Are all commodity conversions declared explicitly ?-- You can use the check command to run individual checks – the ones-listed above and some more.---File: hledger.info, Node: Commands, Next: Output, Prev: Input, Up: Top--5 Commands-**********--hledger provides a number of built-in subcommands (described below).-Most of these read your data without changing it, and display a report.-A few assist with data entry and management.-- Run ‘hledger’ with no arguments to list the commands available, and-‘hledger CMD’ to run a command. CMD can be the full command name, or-its standard abbreviation shown in the commands list, or any unambiguous-prefix of the name. Eg: ‘hledger bal’.--* Menu:--* Add-on commands::---File: hledger.info, Node: Add-on commands, Up: Commands--5.1 Add-on commands-===================--Add-on commands are extra subcommands provided by programs or scripts in-your PATH-- • whose name starts with ‘hledger-’- • whose name ends with a recognised file extension:- ‘.bat’,‘.com’,‘.exe’, ‘.hs’,‘.lhs’,‘.pl’,‘.py’,‘.rb’,‘.rkt’,‘.sh’- or none- • and (on unix, mac) which are executable by the current user.-- Addons can be written in any language, but haskell scripts or-programs have a big advantage: they can use hledger’s library code, for-command-line options, parsing and reporting.-- Several add-on commands are installed by the hledger-install script.-See https://hledger.org/scripts.html for more details.-- Note in a hledger command line, add-on command flags must have a-double dash (‘--’) preceding them. Eg you must write:--$ hledger web -- --serve-- and not:--$ hledger web --serve-- (because the ‘--serve’ flag belongs to ‘hledger-web’, not ‘hledger’).-- The ‘-h/--help’ and ‘--version’ flags don’t require ‘--’.-- If you have any trouble with this, remember you can always run the-add-on program directly, eg:--$ hledger-web --serve---File: hledger.info, Node: Output, Next: Limitations, Prev: Commands, Up: Top--6 Output-********--* Menu:--* Output destination::-* Output format::-* Commodity styles::-* Colour::-* Box-drawing::-* Debug output::---File: hledger.info, Node: Output destination, Next: Output format, Up: Output--6.1 Output destination-======================--hledger commands send their output to the terminal by default. You can-of course redirect this, eg into a file, using standard shell syntax:--$ hledger print > foo.txt-- Some commands (print, register, stats, the balance commands) also-provide the ‘-o/--output-file’ option, which does the same thing without-needing the shell. Eg:--$ hledger print -o foo.txt-$ hledger print -o - # write to stdout (the default)---File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output--6.2 Output format-=================--Some commands offer other kinds of output, not just text on the-terminal. Here are those commands and the formats currently supported:--- txt csv html json sql-------------------------------------------------------------------------------aregister Y Y Y Y-balance Y _1_ Y _1_ Y _1,2_ Y-balancesheet Y _1_ Y _1_ Y _1_ Y-balancesheetequity Y _1_ Y _1_ Y _1_ Y-cashflow Y _1_ Y _1_ Y _1_ Y-incomestatement Y _1_ Y _1_ Y _1_ Y-print Y Y Y Y-register Y Y Y-- • _1 Also affected by the balance commands’ ‘--layout’ option._- • _2 ‘balance’ does not support html output without a report interval- or with ‘--budget’._-- The output format is selected by the ‘-O/--output-format=FMT’ option:--$ hledger print -O csv # print CSV on stdout-- or by the filename extension of an output file specified with the-‘-o/--output-file=FILE.FMT’ option:--$ hledger balancesheet -o foo.csv # write CSV to foo.csv-- The ‘-O’ option can be combined with ‘-o’ to override the file-extension, if needed:--$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt-- Some notes about the various output formats:--* Menu:--* CSV output::-* HTML output::-* JSON output::-* SQL output::---File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format--6.2.1 CSV output------------------- • In CSV output, digit group marks (such as thousands separators) are- disabled automatically.---File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format--6.2.2 HTML output-------------------- • HTML output can be styled by an optional ‘hledger.css’ file in the- same directory.---File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format--6.2.3 JSON output-------------------- • This is not yet much used; real-world feedback is welcome.-- • Our JSON is rather large and verbose, since it is a faithful- representation of hledger’s internal data types. To understand the- JSON, read the Haskell type definitions, which are mostly in- https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.-- • hledger represents quantities as Decimal values storing up to 255- significant digits, eg for repeating decimals. Such numbers can- arise in practice (from automatically-calculated transaction- prices), and would break most JSON consumers. So in JSON, we show- quantities as simple Numbers with at most 10 decimal places. We- don’t limit the number of integer digits, but that part is under- your control. We hope this approach will not cause problems in- practice; if you find otherwise, please let us know. (Cf #1195)---File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format--6.2.4 SQL output------------------- • This is not yet much used; real-world feedback is welcome.-- • SQL output is expected to work with sqlite, MySQL and PostgreSQL-- • SQL output is structured with the expectations that statements will- be executed in the empty database. If you already have tables- created via SQL output of hledger, you would probably want to- either clear tables of existing data (via ‘delete’ or ‘truncate’- SQL statements) or drop tables completely as otherwise your- postings will be duped.---File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output--6.3 Commodity styles-====================--When displaying amounts, hledger infers a standard display style for-each commodity/currency, as described below in Commodity display style.-- If needed, this can be overridden by a ‘-c/--commodity-style’ option-(except for cost amounts and amounts displayed by the ‘print’ command,-which are always displayed with all decimal digits). For example, the-following will force dollar amounts to be displayed as shown:--$ hledger print -c '$1.000,0'-- This option can repeated to set the display style for multiple-commodities/currencies. Its argument is as described in the commodity-directive.---File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output--6.4 Colour-==========--In terminal output, some commands can produce colour when the terminal-supports it:-- • if the ‘--color/--colour’ option is given a value of ‘yes’ or- ‘always’ (or ‘no’ or ‘never’), colour will (or will not) be used;- • otherwise, if the ‘NO_COLOR’ environment variable is set, colour- will not be used;- • otherwise, colour will be used if the output (terminal or file)- supports it.---File: hledger.info, Node: Box-drawing, Next: Debug output, Prev: Colour, Up: Output--6.5 Box-drawing-===============--In terminal output, you can enable unicode box-drawing characters to-render prettier tables:-- • if the ‘--pretty’ option is given a value of ‘yes’ or ‘always’ (or- ‘no’ or ‘never’), unicode characters will (or will not) be used;- • otherwise, unicode characters will not be used.---File: hledger.info, Node: Debug output, Prev: Box-drawing, Up: Output--6.6 Debug output-================--We intend hledger to be relatively easy to troubleshoot, introspect and-develop. You can add ‘--debug[=N]’ to any hledger command line to see-additional debug output. N ranges from 1 (least output, the default) to-9 (maximum output). Typically you would start with 1 and increase until-you are seeing enough. Debug output goes to stderr, and is not affected-by ‘-o/--output-file’ (unless you redirect stderr to stdout, eg:-‘2>&1’). It will be interleaved with normal output, which can help-reveal when parts of the code are evaluated. To capture debug output in-a log file instead, you can usually redirect stderr, eg:--hledger bal --debug=3 2>hledger.log---File: hledger.info, Node: Limitations, Next: Troubleshooting, Prev: Output, Up: Top--7 Limitations-*************--The need to precede add-on command options with ‘--’ when invoked from-hledger is awkward.-- When input data contains non-ascii characters, a suitable system-locale must be configured (or there will be an unhelpful error). Eg on-POSIX, set LANG to something other than C.-- In a Microsoft Windows CMD window, non-ascii characters and colours-are not supported.-- On Windows, non-ascii characters may not display correctly when-running a hledger built in CMD in MSYS/CYGWIN, or vice-versa.-- In a Cygwin/MSYS/Mintty window, the tab key is not supported in-hledger add.-- Not all of Ledger’s journal file syntax is supported. See hledger-and Ledger > Differences > journal format.-- On large data files, hledger is slower and uses more memory than-Ledger.---File: hledger.info, Node: Troubleshooting, Next: PART 2 DATA FORMATS, Prev: Limitations, Up: Top--8 Troubleshooting-*****************--Here are some issues you might encounter when you run hledger (and-remember you can also seek help from the IRC channel, mail list or bug-tracker):-- *Successfully installed, but "No command ’hledger’ found"*-stack and cabal install binaries into a special directory, which should-be added to your PATH environment variable. Eg on unix-like systems,-that is ~/.local/bin and ~/.cabal/bin respectively.-- *I set a custom LEDGER_FILE, but hledger is still using the default-file*-‘LEDGER_FILE’ should be a real environment variable, not just a shell-variable. The command ‘env | grep LEDGER_FILE’ should show it. You may-need to use ‘export’. Here’s an explanation.-- *Getting errors like "Illegal byte sequence" or "Invalid or-incomplete multibyte or wide character" or "commitAndReleaseBuffer:-invalid argument (invalid character)"*-Programs compiled with GHC (hledger, haskell build tools, etc.) need to-have a UTF-8-aware locale configured in the environment, otherwise they-will fail with these kinds of errors when they encounter non-ascii-characters.-- To fix it, set the LANG environment variable to some locale which-supports UTF-8. The locale you choose must be installed on your system.-- Here’s an example of setting LANG temporarily, on Ubuntu GNU/Linux:--$ file my.journal-my.journal: UTF-8 Unicode text # the file is UTF8-encoded-$ echo $LANG-C # LANG is set to the default locale, which does not support UTF8-$ locale -a # which locales are installed ?-C-en_US.utf8 # here's a UTF8-aware one we can use-POSIX-$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command-- If available, ‘C.UTF-8’ will also work. If your preferred locale-isn’t listed by ‘locale -a’, you might need to install it. Eg on-Ubuntu/Debian:--$ apt-get install language-pack-fr-$ locale -a-C-en_US.utf8-fr_BE.utf8-fr_CA.utf8-fr_CH.utf8-fr_FR.utf8-fr_LU.utf8-POSIX-$ LANG=fr_FR.utf8 hledger -f my.journal print-- Here’s how you could set it permanently, if you use a bash shell:--$ echo "export LANG=en_US.utf8" >>~/.bash_profile-$ bash --login-- Exact spelling and capitalisation may be important. Note the-difference on MacOS (‘UTF-8’, not ‘utf8’). Some platforms (eg ubuntu)-allow variant spellings, but others (eg macos) require it to be exact:--$ locale -a | grep -iE en_us.*utf-en_US.UTF-8-$ LANG=en_US.UTF-8 hledger -f my.journal print---File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Troubleshooting, Up: Top--9 PART 2: DATA FORMATS-**********************---File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top--10 Journal-**********--hledger’s default file format, representing a General Journal. Here’s a-cheatsheet/mini-tutorial, or you can skip ahead to About journal format.--* Menu:--* Journal cheatsheet::-* About journal format::-* Comments::-* Transactions::-* Dates::-* Status::-* Code::-* Description::-* Transaction comments::-* Postings::-* Account names::-* Amounts::-* Costs::-* Balance assertions::-* Posting comments::-* Tags::-* Directives::-* account directive::-* alias directive::-* commodity directive::-* decimal-mark directive::-* include directive::-* P directive::-* payee directive::-* tag directive::-* Periodic transactions::-* Other syntax::---File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal--10.1 Journal cheatsheet-=======================--# Here is the main syntax of hledger's journal format-# (omitting extra Ledger compatibility syntax).-# hledger journals contain comments, directives, and transactions, in any order:--###############################################################################-# 1. Comment lines are for notes or temporarily disabling things.-# They begin with #, ;, or a line containing the word "comment".--# hash comment line-; semicolon comment line-comment-These lines-are commented.-end comment--# Some but not all hledger entries can have same-line comments attached to them,-# from ; (semicolon) to end of line.--###############################################################################-# 2. Directives modify parsing or reports in some way.-# They begin with a word or letter (or symbol).--account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;.-account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX)-alias chkg = assets:checking-commodity $0.00-decimal-mark .-include /dev/null-payee Whole Foods-P 2022-01-01 AAAA $1.40-~ monthly budget goals ; <- 2+ spaces between period expression and description- expenses:food $400- expenses:home $1000- budgeted--###############################################################################-# 3. Transactions are what it's all about; they are dated events,-# usually describing movements of money.-# They begin with a date.--# DATE DESCRIPTION ; This is a transaction comment.-# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment.-# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented.-# ; ^^ At least 2 spaces between account and amount.-# ... ; Any number of postings is allowed. The amounts must balance (sum to 0).--2022-01-01 opening balances are declared this way- assets:checking $1000 ; Account names can be anything. lower case is easy to type.- assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common.- assets:cash:wallet $100 ; : indicates subaccounts.- liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative.- equity ; One amount can be left blank; $-1900 is inferred here.--2022-04-15 * (#12345) pay taxes- ; There can be a ! or * after the date meaning "pending" or "cleared".- ; There can be a transaction code (text in parentheses) after the date/status.- ; Amounts' sign represents direction of flow, or credit/debit:- assets:checking $-500 ; minus means removed from this account (credit)- expenses:tax:us:2021 $500 ; plus means added to this account (debit)- ; revenue/expense categories are also "accounts"--Kv-2022-01-01 ; The description is optional.- ; Any currency/commodity symbols are allowed, on either side.- assets:cash:wallet GBP -10- expenses:clothing GBP 10- assets:gringotts -10 gold- assets:pouch 10 gold- revenues:gifts -2 "Liquorice Wands" ; Complex symbols- assets:bag 2 "Liquorice Wands" ; must be double-quoted.--2022-01-01 Cost in another commodity can be noted with @ or @@- assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost- assets:investments 3.0 AAAA @@ $4 ; @@ means total cost- assets:checking $-7.00--2022-01-02 assert balances- ; Balances can be asserted for extra error checking, in any transaction.- assets:investments 0 AAAA = 5.0 AAAA- assets:pouch 0 gold = 10 gold- assets:savings $0 = $1000--1999-12-31 Ordering transactions by date is recommended but not required.- ; Postings are not required.--2022.01.01 These date-2022/1/1 formats are-12/31 also allowed (but consistent YYYY-MM-DD is recommended).---File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal--10.2 About journal format-=========================--hledger’s usual data source is a plain text file containing journal-entries in hledger journal format. This file represents a standard-accounting general journal. I use file names ending in ‘.journal’, but-that’s not required. The journal file contains a number of transaction-entries, each describing a transfer of money (or any commodity) between-two or more named accounts, in a simple format readable by both hledger-and humans.-- hledger’s journal format is a compatible subset, mostly, of ledger’s-journal format, so hledger can work with compatible ledger journal files-as well. It’s safe, and encouraged, to run both hledger and ledger on-the same journal file, eg to validate the results you’re getting.-- You can use hledger without learning any more about this file; just-use the add or web or import commands to create and update it.-- Many users, though, edit the journal file with a text editor, and-track changes with a version control system such as git. Editor addons-such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and-hledger-vscode for Visual Studio Code, make this easier, adding colour,-formatting, tab completion, and useful commands. See Editor-configuration at hledger.org for the full list.-- Here’s a description of each part of the file format (and hledger’s-data model).-- A hledger journal file can contain three kinds of thing: file-comments, transactions, and/or directives (counting periodic transaction-rules and auto posting rules as directives).---File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal--10.3 Comments-=============--Lines in the journal will be ignored if they begin with a hash (‘#’) or-a semicolon (‘;’). (See also Other syntax.) hledger will also ignore-regions beginning with a ‘comment’ line and ending with an ‘end comment’-line (or file end). Here’s a suggestion for choosing between them:-- • ‘#’ for top-level notes- • ‘;’ for commenting out things temporarily- • ‘comment’ for quickly commenting large regions (remember it’s- there, or you might get confused)-- Eg:--# a comment line-; another commentline-comment-A multi-line comment block,-continuing until "end comment" directive-or the end of the current file.-end comment-- Some hledger entries can have same-line comments attached to them,-from ; (semicolon) to end of line. See Transaction comments, Posting-comments, and Account comments below.---File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal--10.4 Transactions-=================--Transactions are the main unit of information in a journal file. They-represent events, typically a movement of some quantity of commodities-between two or more named accounts.-- Each transaction is recorded as a journal entry, beginning with a-simple date in column 0. This can be followed by any of the following-optional fields, separated by spaces:-- • a status character (empty, ‘!’, or ‘*’)- • a code (any short number or text, enclosed in parentheses)- • a description (any remaining text until end of line or a semicolon)- • a comment (any remaining text following a semicolon until end of- line, and any following indented lines beginning with a semicolon)- • 0 or more indented _posting_ lines, describing what was transferred- and the accounts involved (indented comment lines are also allowed,- but not blank lines or non-indented lines).-- Here’s a simple journal file containing one transaction:--2008/01/01 income- assets:bank:checking $1- income:salary $-1---File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal--10.5 Dates-==========--* Menu:--* Simple dates::-* Posting dates::---File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates--10.5.1 Simple dates----------------------Dates in the journal file use _simple dates_ format: ‘YYYY-MM-DD’ or-‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, with leading zeros optional. The year may-be omitted, in which case it will be inferred from the context: the-current transaction, the default year set with a ‘Y’ directive, or the-current date when the command is run. Some examples: ‘2010-01-31’,-‘2010/01/31’, ‘2010.1.31’, ‘1/31’.-- (The UI also accepts simple dates, as well as the more flexible smart-dates documented in the hledger manual.)---File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates--10.5.2 Posting dates-----------------------You can give individual postings a different date from their parent-transaction, by adding a posting comment containing a tag (see below)-like ‘date:DATE’. This is probably the best way to control posting-dates precisely. Eg in this example the expense should appear in May-reports, and the deduction from checking should be reported on 6/1 for-easy bank reconciliation:--2015/5/30- expenses:food $10 ; food purchased on saturday 5/30- assets:checking ; bank cleared it on monday, date:6/1--$ hledger -f t.j register food-2015-05-30 expenses:food $10 $10--$ hledger -f t.j register checking-2015-06-01 assets:checking $-10 $-10-- DATE should be a simple date; if the year is not specified it will-use the year of the transaction’s date.-The ‘date:’ tag must have a valid simple date value if it is present, eg-a ‘date:’ tag with no value is not allowed.---File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal--10.6 Status-===========--Transactions, or individual postings within a transaction, can have a-status mark, which is a single character before the transaction-description or posting account name, separated from it by a space,-indicating one of three statuses:--mark status- ------------------- unmarked-‘!’ pending-‘*’ cleared-- When reporting, you can filter by status with the ‘-U/--unmarked’,-‘-P/--pending’, and ‘-C/--cleared’ flags; or the ‘status:’, ‘status:!’,-and ‘status:*’ queries; or the U, P, C keys in hledger-ui.-- Note, in Ledger and in older versions of hledger, the "unmarked"-state is called "uncleared". As of hledger 1.3 we have renamed it to-unmarked for clarity.-- To replicate Ledger and old hledger’s behaviour of also matching-pending, combine -U and -P.-- Status marks are optional, but can be helpful eg for reconciling with-real-world accounts. Some editor modes provide highlighting and-shortcuts for working with status. Eg in Emacs ledger-mode, you can-toggle transaction status with C-c C-e, or posting status with C-c C-c.-- What "uncleared", "pending", and "cleared" actually mean is up to-you. Here’s one suggestion:--status meaning----------------------------------------------------------------------------uncleared recorded but not yet reconciled; needs review-pending tentatively reconciled (if needed, eg during a big- reconciliation)-cleared complete, reconciled as far as possible, and considered- correct-- With this scheme, you would use ‘-PC’ to see the current balance at-your bank, ‘-U’ to see things which will probably hit your bank soon-(like uncashed checks), and no flags to see the most up-to-date state of-your finances.---File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal--10.7 Code-=========--After the status mark, but before the description, you can optionally-write a transaction "code", enclosed in parentheses. This is a good-place to record a check number, or some other important transaction id-or reference number.---File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal--10.8 Description-================--A transaction’s description is the rest of the line following the date-and status mark (or until a comment begins). Sometimes called the-"narration" in traditional bookkeeping, it can be used for whatever you-wish, or left blank. Transaction descriptions can be queried, unlike-comments.--* Menu:--* Payee and note::---File: hledger.info, Node: Payee and note, Up: Description--10.8.1 Payee and note------------------------You can optionally include a ‘|’ (pipe) character in descriptions to-subdivide the description into separate fields for payee/payer name on-the left (up to the first ‘|’) and an additional note field on the right-(after the first ‘|’). This may be worthwhile if you need to do more-precise querying and pivoting by payee or by note.---File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal--10.9 Transaction comments-=========================--Text following ‘;’, after a transaction description, and/or on indented-lines immediately below it, form comments for that transaction. They-are reproduced by ‘print’ but otherwise ignored, except they may contain-tags, which are not ignored.--2012-01-01 something ; a transaction comment- ; a second line of transaction comment- expenses 1- assets---File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal--10.10 Postings-==============--A posting is an addition of some amount to, or removal of some amount-from, an account. Each posting line begins with at least one space or-tab (2 or 4 spaces is common), followed by:-- • (optional) a status character (empty, ‘!’, or ‘*’), followed by a- space- • (required) an account name (any text, optionally containing *single- spaces*, until end of line or a double space)- • (optional) *two or more spaces* or tabs followed by an amount.-- Positive amounts are being added to the account, negative amounts are-being removed.-- The amounts within a transaction must always sum up to zero. As a-convenience, one amount may be left blank; it will be inferred so as to-balance the transaction.-- Be sure to note the unusual two-space delimiter between account name-and amount. This makes it easy to write account names containing-spaces. But if you accidentally leave only one space (or tab) before-the amount, the amount will be considered part of the account name.---File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal--10.11 Account names-===================--Accounts are the main way of categorising things in hledger. As in-Double Entry Bookkeeping, they can represent real world accounts (such-as a bank account), or more abstract categories such as "money borrowed-from Frank" or "money spent on electricity".-- You can use any account names you like, but we usually start with the-traditional accounting categories, which in english are ‘assets’,-‘liabilities’, ‘equity’, ‘revenues’, ‘expenses’. (You might see these-referred to as A, L, E, R, X for short.)-- For more precise reporting, we usually divide the top level accounts-into more detailed subaccounts, by writing a full colon between account-name parts. For example, from the account names ‘assets:bank:checking’-and ‘expenses:food’, hledger will infer this hierarchy of five accounts:--assets-assets:bank-assets:bank:checking-expenses-expenses:food-- Shown as an outline, the hierarchical tree structure is more clear:--assets- bank- checking-expenses- food-- hledger reports can summarise the account tree to any depth, so you-can go as deep as you like with subcategories, but keeping your account-names relatively simple may be best when starting out.-- Account names may be capitalised or not; they may contain letters,-numbers, symbols, or single spaces. Note, when an account name and an-amount are written on the same line, they must be separated by *two or-more spaces* (or tabs).-- Parentheses or brackets enclosing the full account name indicate-virtual postings, described below. Parentheses or brackets internal to-the account name have no special meaning.-- Account names can be altered temporarily or permanently by account-aliases.---File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal--10.12 Amounts-=============--After the account name, there is usually an amount. (Important: between-account name and amount, there must be *two or more spaces*.)-- hledger’s amount format is flexible, supporting several international-formats. Here are some examples. Amounts have a number (the-"quantity"):--1-- ..and usually a currency symbol or commodity name (more on this-below), to the left or right of the quantity, with or without a-separating space:--$1-4000 AAPL-3 "green apples"-- Amounts can be preceded by a minus sign (or a plus sign, though plus-is the default), The sign can be written before or after a left-side-commodity symbol:---$1-$-1-- One or more spaces between the sign and the number are acceptable-when parsing (but they won’t be displayed in output):--+ $1-$- 1-- Scientific E notation is allowed:--1E-6-EUR 1E3--* Menu:--* Decimal marks digit group marks::-* Commodity::-* Directives influencing number parsing and display::-* Commodity display style::-* Rounding::---File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts--10.12.1 Decimal marks, digit group marks-------------------------------------------A _decimal mark_ can be written as a period or a comma:--1.23-1,23456780000009-- In the integer part of the quantity (left of the decimal mark),-groups of digits can optionally be separated by a _digit group mark_ - a-space, comma, or period (different from the decimal mark):-- $1,000,000.00- EUR 2.000.000,00-INR 9,99,99,999.00- 1 000 000.9455-- Note, a number containing a single digit group mark and no decimal-mark is ambiguous. Are these digit group marks or decimal marks ?--1,000-1.000-- If you don’t tell it otherwise, hledger will assume both of the above-are decimal marks, parsing both numbers as 1.-- To prevent confusing parsing mistakes and undetected typos,-especially if your data contains digit group marks (eg, thousands-separators), we recommend explicitly declaring the decimal mark-character in each journal file, using a directive at the top of the-file. The ‘decimal-mark’ directive is best, otherwise ‘commodity’-directives will also work. These are described below.---File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts--10.12.2 Commodity--------------------Amounts in hledger have both a "quantity", which is a signed decimal-number, and a "commodity", which is a currency symbol, stock ticker, or-any word or phrase describing something you are tracking.-- If the commodity name contains non-letters (spaces, numbers, or-punctuation), you must always write it inside double quotes (‘"green-apples"’, ‘"ABC123"’).-- If you write just a bare number, that too will have a commodity, with-name ‘""’; we call that the "no-symbol commodity".-- Actually, hledger combines these single-commodity amounts into more-powerful multi-commodity amounts, which are what it works with most of-the time. A multi-commodity amount could be, eg: ‘1 USD, 2 EUR, 3.456-TSLA’. In practice, you will only see multi-commodity amounts in-hledger’s output; you can’t write them directly in the journal file.-- (If you are writing scripts or working with hledger’s internals,-these are the ‘Amount’ and ‘MixedAmount’ types.)---File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts--10.12.3 Directives influencing number parsing and display------------------------------------------------------------You can add ‘decimal-mark’ and ‘commodity’ directives to the journal, to-declare and control these things more explicitly and precisely. These-are described below, but here’s a quick example:--# the decimal mark character used by all amounts in this file (all commodities)-decimal-mark .--# display styles for the $, EUR, INR and no-symbol commodities:-commodity $1,000.00-commodity EUR 1.000,00-commodity INR 9,99,99,999.00-commodity 1 000 000.9455---File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts--10.12.4 Commodity display style----------------------------------For the amounts in each commodity, hledger chooses a consistent display-style to use in most reports. (Exceptions: price amounts, and all-amounts displayed by the ‘print’ command, are displayed with all of-their decimal digits visible.)-- A commodity’s display style is inferred as follows.-- First, if a default commodity is declared with ‘D’, this commodity-and its style is applied to any no-symbol amounts in the journal.-- Then each commodity’s style is inferred from one of the following, in-order of preference:-- • The commodity directive for that commodity (including the no-symbol- commodity), if any.- • The amounts in that commodity seen in the journal’s transactions.- (Posting amounts only; prices and periodic or auto rules are- ignored, currently.)- • The built-in fallback style, which looks like this: ‘$1000.00’.- (Symbol on the left, period decimal mark, two decimal places.)-- A style is inferred from journal amounts as follows:-- • Use the general style (decimal mark, symbol placement) of the first- amount- • Use the first-seen digit group style (digit group mark, digit group- sizes), if any- • Use the maximum number of decimal places of all.-- Cost amounts don’t affect the commodity display style directly, but-occasionally they can do so indirectly (eg when a posting’s amount is-inferred using a cost). If you find this causing problems, use a-commodity directive to fix the display style.-- To summarise: each commodity’s amounts will be normalised to (a) the-style declared by a ‘commodity’ directive, or (b) the style of the first-posting amount in the journal, with the first-seen digit group style and-the maximum-seen number of decimal places. So if your reports are-showing amounts in a way you don’t like, eg with too many decimal-places, use a commodity directive. Some examples:--# declare euro, dollar, bitcoin and no-symbol commodities and set their -# input number formats and output display styles:-commodity EUR 1.000,-commodity $1000.00-commodity 1000.00000000 BTC-commodity 1 000.-- The inferred commodity style can be overridden by supplying a command-line option.---File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts--10.12.5 Rounding-------------------Amounts are stored internally as decimal numbers with up to 255 decimal-places, and displayed with the number of decimal places specified by the-commodity display style. Note, hledger uses banker’s rounding: it-rounds to the nearest even number, eg 0.5 displayed with zero decimal-places is "0").---File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal--10.13 Costs-===========--After a posting amount, you can note its cost (when buying) or selling-price (when selling) in another commodity, by writing either ‘@-UNITPRICE’ or ‘@@ TOTALPRICE’ after it. This indicates a conversion-transaction, where one commodity is exchanged for another.-- (You might also see this called "transaction price" in hledger docs,-discussions, or code; that term was directionally neutral and reminded-that it is a price specific to a transaction, but we now just call it-"cost", with the understanding that the transaction could be a purchase-or a sale.)-- Costs are usually written explicitly with ‘@’ or ‘@@’, but can also-be inferred automatically for simple multi-commodity transactions.-Note, if costs are inferred, the order of postings is significant; the-first posting will have a cost attached, in the commodity of the second.-- As an example, here are several ways to record purchases of a foreign-currency in hledger, using the cost notation either explicitly or-implicitly:-- 1. Write the price per unit, as ‘@ UNITPRICE’ after the amount:-- 2009/1/1- assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each- assets:dollars ; balancing amount is -$135.00-- 2. Write the total price, as ‘@@ TOTALPRICE’ after the amount:-- 2009/1/1- assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot- assets:dollars-- 3. Specify amounts for all postings, using exactly two commodities,- and let hledger infer the price that balances the transaction.- Note the effect of posting order: the price is added to first- posting, making it ‘€100 @@ $135’, as in example 2:-- 2009/1/1- assets:euros €100 ; one hundred euros purchased- assets:dollars $-135 ; for $135-- Amounts can be converted to cost at report time using the ‘-B/--cost’-flag; this is discussed more in the ˜COST REPORTING section.--* Menu:--* Other cost/lot notations::---File: hledger.info, Node: Other cost/lot notations, Up: Costs--10.13.1 Other cost/lot notations-----------------------------------A slight digression for Ledger and Beancount users. Ledger has a number-of cost/lot-related notations:-- • ‘@ UNITCOST’ and ‘@@ TOTALCOST’- • expresses a conversion rate, as in hledger- • when buying, also creates a lot than can be selected at- selling time-- • ‘(@) UNITCOST’ and ‘(@@) TOTALCOST’ (virtual cost)- • like the above, but also means "this cost was exceptional,- don’t use it when inferring market prices".-- Currently, hledger treats the above like ‘@’ and ‘@@’; the-parentheses are ignored.-- • ‘{=FIXEDUNITCOST}’ and ‘{{=FIXEDTOTALCOST}}’ (fixed price)- • when buying, means "this cost is also the fixed price, don’t- let it fluctuate in value reports"-- • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ (lot price)- • can be used identically to ‘@ UNITCOST’ and ‘@@ TOTALCOST’,- also creates a lot- • when selling, combined with ‘@ ...’, specifies an investment- lot by its cost basis; does not check if that lot is present-- • and related: ‘[YYYY/MM/DD]’ (lot date)- • when buying, attaches this acquisition date to the lot- • when selling, selects a lot by its acquisition date-- • ‘(SOME TEXT)’ (lot note)- • when buying, attaches this note to the lot- • when selling, selects a lot by its note-- Currently, hledger accepts any or all of the above in any order after-the posting amount, but ignores them. (This can break transaction-balancing.)-- For Beancount users, the notation and behaviour is different:-- • ‘@ UNITCOST’ and ‘@@ TOTALCOST’- • expresses a cost without creating a lot, as in hledger- • when buying (augmenting) or selling (reducing) a lot, combined- with ‘{...}’: documents the cost/selling price (not used for- transaction balancing)-- • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’- • when buying (augmenting), expresses the cost for transaction- balancing, and also creates a lot with this cost basis- attached- • when selling (reducing),- • selects a lot by its cost basis- • raises an error if that lot is not present or can not be- selected unambiguously (depending on booking method- configured)- • expresses the selling price for transaction balancing-- Currently, hledger accepts the ‘{UNITCOST}’/‘{{TOTALCOST}}’ notation-but ignores it.-- • variations: ‘{}’, ‘{YYYY-MM-DD}’, ‘{"LABEL"}’, ‘{UNITCOST,- "LABEL"}’, ‘{UNITCOST, YYYY-MM-DD, "LABEL"}’ etc.-- Currently, hledger rejects these.---File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal--10.14 Balance assertions-========================--hledger supports Ledger-style balance assertions in journal files.-These look like, for example, ‘= EXPECTEDBALANCE’ following a posting’s-amount. Eg here we assert the expected dollar balance in accounts a and-b after each posting:--2013/1/1- a $1 =$1- b =$-1--2013/1/2- a $1 =$2- b $-1 =$-2-- After reading a journal file, hledger will check all balance-assertions and report an error if any of them fail. Balance assertions-can protect you from, eg, inadvertently disrupting reconciled balances-while cleaning up old entries. You can disable them temporarily with-the ‘-I/--ignore-assertions’ flag, which can be useful for-troubleshooting or for reading Ledger files. (Note: this flag currently-does not disable balance assignments, described below).--* Menu:--* Assertions and ordering::-* Assertions and multiple included files::-* Assertions and multiple -f files::-* Assertions and commodities::-* Assertions and prices::-* Assertions and subaccounts::-* Assertions and virtual postings::-* Assertions and auto postings::-* Assertions and precision::---File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions--10.14.1 Assertions and ordering----------------------------------hledger sorts an account’s postings and assertions first by date and-then (for postings on the same day) by parse order. Note this is-different from Ledger, which sorts assertions only by parse order.-(Also, Ledger assertions do not see the accumulated effect of repeated-postings to the same account within a transaction.)-- So, hledger balance assertions keep working if you reorder-differently-dated transactions within the journal. But if you reorder-same-dated transactions or postings, assertions might break and require-updating. This order dependence does bring an advantage: precise-control over the order of postings and assertions within a day, so you-can assert intra-day balances.---File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions--10.14.2 Assertions and multiple included files-------------------------------------------------Multiple files included with the ‘include’ directive are processed as if-concatenated into one file, preserving their order and the posting order-within each file. It means that balance assertions in later files will-see balance from earlier files.-- And if you have multiple postings to an account on the same day,-split across multiple files, and you want to assert the account’s-balance on that day, you’ll need to put the assertion in the right file-- the last one in the sequence, probably.---File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions--10.14.3 Assertions and multiple -f files-------------------------------------------Unlike ‘include’, when multiple files are specified on the command line-with multiple ‘-f/--file’ options, balance assertions will not see-balance from earlier files. This can be useful when you do not want-problems in earlier files to disrupt valid assertions in later files.-- If you do want assertions to see balance from earlier files, use-‘include’, or concatenate the files temporarily.---File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions--10.14.4 Assertions and commodities-------------------------------------The asserted balance must be a simple single-commodity amount, and in-fact the assertion checks only this commodity’s balance within the-(possibly multi-commodity) account balance. This is how assertions work-in Ledger also. We could call this a "partial" balance assertion.-- To assert the balance of more than one commodity in an account, you-can write multiple postings, each asserting one commodity’s balance.-- You can make a stronger "total" balance assertion by writing a double-equals sign (‘== EXPECTEDBALANCE’). This asserts that there are no-other commodities in the account besides the asserted one (or at least,-that their balance is 0).--2013/1/1- a $1- a 1€- b $-1- c -1€--2013/1/2 ; These assertions succeed- a 0 = $1- a 0 = 1€- b 0 == $-1- c 0 == -1€--2013/1/3 ; This assertion fails as 'a' also contains 1€- a 0 == $1-- It’s not yet possible to make a complete assertion about a balance-that has multiple commodities. One workaround is to isolate each-commodity into its own subaccount:--2013/1/1- a:usd $1- a:euro 1€- b--2013/1/2- a 0 == 0- a:usd 0 == $1- a:euro 0 == 1€---File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions--10.14.5 Assertions and prices--------------------------------Balance assertions ignore costs, and should normally be written without-one:--2019/1/1- (a) $1 @ €1 = $1-- We do allow prices to be written there, however, and print shows-them, even though they don’t affect whether the assertion passes or-fails. This is for backward compatibility (hledger’s close command used-to generate balance assertions with prices), and because balance-_assignments_ do use them (see below).---File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions--10.14.6 Assertions and subaccounts-------------------------------------The balance assertions above (‘=’ and ‘==’) do not count the balance-from subaccounts; they check the account’s exclusive balance only. You-can assert the balance including subaccounts by writing ‘=*’ or ‘==*’,-eg:--2019/1/1- equity:opening balances- checking:a 5- checking:b 5- checking 1 ==* 11---File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions--10.14.7 Assertions and virtual postings------------------------------------------Balance assertions always consider both real and virtual postings; they-are not affected by the ‘--real/-R’ flag or ‘real:’ query.---File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions--10.14.8 Assertions and auto postings---------------------------------------Balance assertions _are_ affected by the ‘--auto’ flag, which generates-auto postings, which can alter account balances. Because auto postings-are optional in hledger, accounts affected by them effectively have two-balances. But balance assertions can only test one or the other of-these. So to avoid making fragile assertions, either:-- • assert the balance calculated with ‘--auto’, and always use- ‘--auto’ with that file- • or assert the balance calculated without ‘--auto’, and never use- ‘--auto’ with that file- • or avoid balance assertions on accounts affected by auto postings- (or avoid auto postings entirely).---File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions--10.14.9 Assertions and precision-----------------------------------Balance assertions compare the exactly calculated amounts, which are not-always what is shown by reports. Eg a commodity directive may limit the-display precision, but this will not affect balance assertions. Balance-assertion failure messages show exact amounts.---File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal--10.15 Posting comments-======================--Text following ‘;’, at the end of a posting line, and/or on indented-lines immediately below it, form comments for that posting. They are-reproduced by ‘print’ but otherwise ignored, except they may contain-tags, which are not ignored.--2012-01-01- expenses 1 ; a comment for posting 1- assets- ; a comment for posting 2- ; a second comment line for posting 2---File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal--10.16 Tags-==========--Tags are a way to add extra labels or labelled data to transactions,-postings, or accounts, which you can then search or pivot on.-- They are written as a word (optionally hyphenated) immediately-followed by a full colon, in a transaction or posting or account-directive’s comment. (This is an exception to the usual rule that-things in comments are ignored.) Eg, here four different tags are-recorded: one on the checking account, two on the transaction, and one-on the expenses posting:--account assets:checking ; accounttag:--2017/1/16 bought groceries ; transactiontag-1:- ; transactiontag-2:- assets:checking $-1- expenses:food $1 ; postingtag:-- Postings also inherit tags from their transaction and their account.-And transactions also acquire tags from their postings (and postings’-accounts). So in the example above, the expenses posting effectively-has all four tags (by inheriting from account and transaction), and the-transaction also has all four tags (by acquiring from the expenses-posting).-- You can list tag names with ‘hledger tags [NAMEREGEX]’, or match by-tag name with a ‘tag:NAMEREGEX’ query.--* Menu:--* Tag values::---File: hledger.info, Node: Tag values, Up: Tags--10.16.1 Tag values---------------------Tags can have a value, which is any text after the colon up until a-comma or end of line (with surrounding whitespace removed). Note this-means that hledger tag values can not contain commas. Eg in the-following posting, the three tags’ values are "value 1", "value 2", and-"" (empty) respectively:-- expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz-- Note that tags can be repeated, and are additive rather than-overriding: when the same tag name is seen again with a new value, the-new name:value pair is added to the tags. (It is not possible to-override a tag’s value or remove a tag.)-- You can list a tag’s values with ‘hledger tags TAGNAME --values’, or-match by tag value with a ‘tag:NAMEREGEX=VALUEREGEX’ query.---File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal--10.17 Directives-================--A directive is a line in the journal beginning with a special keyword,-that influences how the journal is processed, how things are displayed,-and so on. hledger’s directives are based on (a subset of) Ledger’s,-but there are many differences, and also some differences between-hledger versions. Here are some more definitions:-- • _subdirective_ - Some directives support subdirectives, written- indented below the parent directive.-- • _decimal mark_ - The character to interpret as a decimal mark- (period or comma) when parsing amounts of a commodity.-- • _display style_ - How to display amounts of a commodity in output:- symbol side and spacing, digit groups, decimal mark, and number of- decimal places.-- Directives are not required when starting out with hledger, but you-will probably want to add some as your needs grow. Here some key-directives for particular needs:--purpose directives----------------------------------------------------------------------------*READING DATA:*-Declare file’s decimal mark to help parse ‘decimal-mark’-amounts accurately-Rewrite account names ‘alias’-Comment out sections of the data ‘comment’-Include extra data files ‘include’-*GENERATING DATA:*-Generate recurring transactions or budget ‘~’-goals-Generate extra postings on transactions ‘=’-*CHECKING FOR ERRORS:*-Define valid entities to provide more ‘account’, ‘commodity’,-error checking ‘payee’-*REPORTING:*-Declare accounts’ type and display order ‘account’-Declare commodity display styles ‘commodity’-Declare market prices ‘P’--* Menu:--* Directive effects::-* Directives and multiple files::---File: hledger.info, Node: Directive effects, Next: Directives and multiple files, Up: Directives--10.17.1 Directive effects----------------------------And here is what each directive does, and which files and journal-entries (transactions) it affects:--directivewhat it does ends- at- file- end?-----------------------------------------------------------------------------*‘account’*Declares an account, for checking all entries in all files; andN- its display order and type. Subdirectives: any text, ignored.-*‘alias’*Rewrites account names, in following entries until end of Y- current file or ‘end aliases’. Command line equivalent:- ‘--alias’-*‘comment’*Ignores part of the journal file, until end of current file orY- ‘end comment’.-*‘commodity’*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N- all amounts in all files 2. the decimal mark for parsing- amounts of this commodity, in the following entries until end of- current file (if there is no ‘decimal-mark’ directive) 3. and- the display style for amounts of this commodity 4. which is- also the precision to use for balanced-transaction checking in- this commodity. Takes precedence over ‘D’. Subdirectives:- ‘format’ (Ledger-compatible syntax). Command line equivalent:- ‘-c/--commodity-style’-*‘decimal-mark’*Declares the decimal mark, for parsing amounts of all Y- commodities in following entries until next ‘decimal-mark’ or- end of current file. Included files can override. Takes- precedence over ‘commodity’ and ‘D’.-*‘include’*Includes entries and directives from another file, as if theyN- were written inline. Command line alternative: multiple- ‘-f/--file’-*‘payee’*Declares a payee name, for checking all entries in all files. N-*‘P’*Declares the market price of a commodity on some date, for value N- reports.-*‘~’*Declares a periodic transaction rule that generates future N-(tilde)transactions with ‘--forecast’ and budget goals with ‘balance- --budget’.-Other-syntax:-*‘applyPrepends a common parent account to all account names, in Y-account’*following entries until end of current file or ‘end apply- account’.-*‘D’*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N- there is no ‘commodity’ directive for this commodity: its- decimal mark, balancing precision, and display style, as above.-*‘Y’*Sets a default year to use for any yearless dates, in following Y- entries until end of current file.-*‘=’*Declares an auto posting rule that generates extra postings on partly-(equals)matched transactions with ‘--auto’, in current, parent, and- child files (but not sibling files, see #1212).-*OtherOther directives from Ledger’s file format are accepted but-Ledgerignored.-directives*---File: hledger.info, Node: Directives and multiple files, Prev: Directive effects, Up: Directives--10.17.2 Directives and multiple files----------------------------------------If you use multiple ‘-f’/‘--file’ options, or the ‘include’ directive,-hledger will process multiple input files. But directives which affect-input typically have effect only until the end of the file in which they-occur (and on any included files in that region).-- This may seem inconvenient, but it’s intentional; it makes reports-stable and deterministic, independent of the order of input. Otherwise-you could see different numbers if you happened to write -f options in a-different order, or if you moved includes around while cleaning up your-files.-- It can be surprising though; for example, it means that ‘alias’-directives do not affect parent or sibling files (see below).---File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal--10.18 ‘account’ directive-=========================--‘account’ directives can be used to declare accounts (ie, the places-that amounts are transferred from and to). Though not required, these-declarations can provide several benefits:-- • They can document your intended chart of accounts, providing a- reference.- • In strict mode, they restrict which accounts may be posted to by- transactions, which helps detect typos.- • They control account display order in reports, allowing- non-alphabetic sorting (eg Revenues to appear above Expenses).- • They help with account name completion (in hledger add,- hledger-web, hledger-iadd, ledger-mode, etc.)- • They can store additional account information as comments, or as- tags which can be used to filter or pivot reports.- • They can help hledger know your accounts’ types (asset, liability,- equity, revenue, expense), affecting reports like balancesheet and- incomestatement.-- They are written as the word ‘account’ followed by a hledger-style-account name, eg:--account assets:bank:checking-- Note, however, that accounts declared in account directives are not-allowed to have surrounding brackets and parentheses, unlike accounts-used in postings. So the following journal will not parse:--account (assets:bank:checking)--* Menu:--* Account comments::-* Account subdirectives::-* Account error checking::-* Account display order::-* Account types::---File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive--10.18.1 Account comments---------------------------Text following *two or more spaces* and ‘;’ at the end of an account-directive line, and/or following ‘;’ on indented lines immediately below-it, form comments for that account. They are ignored except they may-contain tags, which are not ignored.-- The two-space requirement for same-line account comments is because-‘;’ is allowed in account names.--account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon- ; next-line comment- ; some tags - type:A, acctnum:12345---File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive--10.18.2 Account subdirectives--------------------------------Ledger-style indented subdirectives are also accepted, but currently-ignored:--account assets:bank:checking- format subdirective is ignored---File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive--10.18.3 Account error checking---------------------------------By default, accounts need not be declared; they come into existence when-a posting references them. This is convenient, but it means hledger-can’t warn you when you mis-spell an account name in the journal.-Usually you’ll find that error later, as an extra account in balance-reports, or an incorrect balance when reconciling.-- In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will-report an error if any transaction uses an account name that has not-been declared by an account directive. Some notes:-- • The declaration is case-sensitive; transactions must use the- correct account name capitalisation.- • The account directive’s scope is "whole file and below" (see- directives). This means it affects all of the current file, and- any files it includes, but not parent or sibling files. The- position of account directives within the file does not matter,- though it’s usual to put them at the top.- • Accounts can only be declared in ‘journal’ files, but will affect- included files of all types.- • It’s currently not possible to declare "all possible subaccounts"- with a wildcard; every account posted to must be declared.---File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive--10.18.4 Account display order--------------------------------The order in which account directives are written influences the order-in which accounts appear in reports, hledger-ui, hledger-web etc. By-default accounts appear in alphabetical order, but if you add these-account directives to the journal file:--account assets-account liabilities-account equity-account revenues-account expenses-- those accounts will be displayed in declaration order:--$ hledger accounts -1-assets-liabilities-equity-revenues-expenses-- Any undeclared accounts are displayed last, in alphabetical order.-- Sorting is done at each level of the account tree, within each group-of sibling accounts under the same parent. And currently, this-directive:--account other:zoo-- would influence the position of ‘zoo’ among ‘other’’s subaccounts,-but not the position of ‘other’ among the top-level accounts. This-means:-- • you will sometimes declare parent accounts (eg ‘account other’- above) that you don’t intend to post to, just to customize their- display order- • sibling accounts stay together (you couldn’t display ‘x:y’ in- between ‘a:b’ and ‘a:c’).---File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive--10.18.5 Account types------------------------hledger knows that accounts come in several types: assets, liabilities,-expenses and so on. This enables easy reports like balancesheet and-incomestatement, and filtering by account type with the ‘type:’ query.-- As a convenience, hledger will detect these account types-automatically if you are using common english-language top-level account-names (described below). But generally we recommend you declare types-explicitly, by adding a ‘type:’ tag to your top-level account-directives. Subaccounts will inherit the type of their parent. The-tag’s value should be one of the five main account types:-- • ‘A’ or ‘Asset’ (things you own)- • ‘L’ or ‘Liability’ (things you owe)- • ‘E’ or ‘Equity’ (investment/ownership; balanced counterpart of- assets & liabilities)- • ‘R’ or ‘Revenue’ (what you received money from, AKA income;- technically part of Equity)- • ‘X’ or ‘Expense’ (what you spend money on; technically part of- Equity)-- or, it can be (these are used less often):-- • ‘C’ or ‘Cash’ (a subtype of Asset, indicating liquid assets for the- cashflow report)- • ‘V’ or ‘Conversion’ (a subtype of Equity, for conversions (see COST- REPORTING).)-- Here is a typical set of account type declarations:--account assets ; type: A-account liabilities ; type: L-account equity ; type: E-account revenues ; type: R-account expenses ; type: X--account assets:bank ; type: C-account assets:cash ; type: C--account equity:conversion ; type: V-- Here are some tips for working with account types.-- • The rules for inferring types from account names are as follows.- These are just a convenience that sometimes help new users get- going; if they don’t work for you, just ignore them and declare- your account types. See also Regular expressions.-- If account's name contains this (CI) regular expression: | its type is:- --------------------------------------------------------------------|-------------- ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash- ^assets?(:|$) | Asset- ^(debts?|liabilit(y|ies))(:|$) | Liability- ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion- ^equity(:|$) | Equity- ^(income|revenue)s?(:|$) | Revenue- ^expenses?(:|$) | Expense-- • If you declare any account types, it’s a good idea to declare an- account for all of the account types, because a mixture of declared- and name-inferred types can disrupt certain reports.-- • Certain uses of account aliases can disrupt account types. See- Rewriting accounts > Aliases and account types.-- • As mentioned above, subaccounts will inherit a type from their- parent account. More precisely, an account’s type is decided by- the first of these that exists:-- 1. A ‘type:’ declaration for this account.- 2. A ‘type:’ declaration in the parent accounts above it,- preferring the nearest.- 3. An account type inferred from this account’s name.- 4. An account type inferred from a parent account’s name,- preferring the nearest parent.- 5. Otherwise, it will have no type.-- • For troubleshooting, you can list accounts and their types with:-- $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]---File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal--10.19 ‘alias’ directive-=======================--You can define account alias rules which rewrite your account names, or-parts of them, before generating reports. This can be useful for:-- • expanding shorthand account names to their full form, allowing- easier data entry and a less verbose journal- • adapting old journals to your current chart of accounts- • experimenting with new account organisations, like a new hierarchy- • combining two accounts into one, eg to see their sum or difference- on one line- • customising reports-- Account aliases also rewrite account names in account directives.-They do not affect account names being entered via hledger add or-hledger-web.-- Account aliases are very powerful. They are generally easy to use-correctly, but you can also generate invalid account names with them;-more on this below.-- See also Rewrite account names.--* Menu:--* Basic aliases::-* Regex aliases::-* Combining aliases::-* Aliases and multiple files::-* end aliases directive::-* Aliases can generate bad account names::-* Aliases and account types::---File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive--10.19.1 Basic aliases------------------------To set an account alias, use the ‘alias’ directive in your journal file.-This affects all subsequent journal entries in the current file or its-included files (but note: not sibling or parent files). The spaces-around the = are optional:--alias OLD = NEW-- Or, you can use the ‘--alias 'OLD=NEW'’ option on the command line.-This affects all entries. It’s useful for trying out aliases-interactively.-- OLD and NEW are case sensitive full account names. hledger will-replace any occurrence of the old account name with the new one.-Subaccounts are also affected. Eg:--alias checking = assets:bank:wells fargo:checking-; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"---File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive--10.19.2 Regex aliases------------------------There is also a more powerful variant that uses a regular expression,-indicated by wrapping the pattern in forward slashes. (This is the only-place where hledger requires forward slashes around a regular-expression.)-- Eg:--alias /REGEX/ = REPLACEMENT-- or:--$ hledger --alias '/REGEX/=REPLACEMENT' ...-- Any part of an account name matched by REGEX will be replaced by-REPLACEMENT. REGEX is case-insensitive as usual.-- If you need to match a forward slash, escape it with a backslash, eg-‘/\/=:’.-- If REGEX contains parenthesised match groups, these can be referenced-by the usual backslash and number in REPLACEMENT:--alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3-; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"-- REPLACEMENT continues to the end of line (or on command line, to end-of option argument), so it can contain trailing whitespace.---File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive--10.19.3 Combining aliases----------------------------You can define as many aliases as you like, using journal directives-and/or command line options.-- Recursive aliases - where an account name is rewritten by one alias,-then by another alias, and so on - are allowed. Each alias sees the-effect of previously applied aliases.-- In such cases it can be important to understand which aliases will be-applied and in which order. For (each account name in) each journal-entry, we apply:-- 1. ‘alias’ directives preceding the journal entry, most recently- parsed first (ie, reading upward from the journal entry, bottom to- top)- 2. ‘--alias’ options, in the order they appeared on the command line- (left to right).-- In other words, for (an account name in) a given journal entry:-- • the nearest alias declaration before/above the entry is applied- first- • the next alias before/above that will be be applied next, and so on- • aliases defined after/below the entry do not affect it.-- This gives nearby aliases precedence over distant ones, and helps-provide semantic stability - aliases will keep working the same way-independent of which files are being read and in which order.-- In case of trouble, adding ‘--debug=6’ to the command line will show-which aliases are being applied when.---File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive--10.19.4 Aliases and multiple files-------------------------------------As explained at Directives and multiple files, ‘alias’ directives do not-affect parent or sibling files. Eg in this command,--hledger -f a.aliases -f b.journal-- account aliases defined in a.aliases will not affect b.journal.-Including the aliases doesn’t work either:--include a.aliases--2020-01-01 ; not affected by a.aliases- foo 1- bar-- This means that account aliases should usually be declared at the-start of your top-most file, like this:--alias foo=Foo-alias bar=Bar--2020-01-01 ; affected by aliases above- foo 1- bar--include c.journal ; also affected---File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive--10.19.5 ‘end aliases’ directive----------------------------------You can clear (forget) all currently defined aliases (seen in the-journal so far, or defined on the command line) with this directive:--end aliases---File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive--10.19.6 Aliases can generate bad account names-------------------------------------------------Be aware that account aliases can produce malformed account names, which-could cause confusing reports or invalid ‘print’ output. For example,-you could erase all account names:--2021-01-01- a:aa 1- b--$ hledger print --alias '/.*/='-2021-01-01- 1-- The above ‘print’ output is not a valid journal. Or you could insert-an illegal double space, causing ‘print’ output that would give a-different journal when reparsed:--2021-01-01- old 1- other--$ hledger print --alias old="new USD" | hledger -f- print-2021-01-01- new USD 1- other---File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive--10.19.7 Aliases and account types------------------------------------If an account with a type declaration (see Declaring accounts > Account-types) is renamed by an alias, normally the account type remains in-effect.-- However, renaming in a way that reshapes the account tree (eg-renaming parent accounts but not their children, or vice versa) could-prevent child accounts from inheriting the account type of their-parents.-- Secondly, if an account’s type is being inferred from its name,-renaming it by an alias could prevent or alter that.-- If you are using account aliases and the ‘type:’ query is not-matching accounts as you expect, try troubleshooting with the accounts-command, eg something like:--$ hledger accounts --alias assets=bassetts type:a---File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal--10.20 ‘commodity’ directive-===========================--You can use ‘commodity’ directives to declare your commodities. In fact-the ‘commodity’ directive performs several functions at once:-- 1. It declares commodities which may be used in the journal. This can- optionally be enforced, providing useful error checking. (Cf- Commodity error checking)-- 2. It declares which decimal mark character (period or comma), to- expect when parsing input - useful to disambiguate international- number formats in your data. Without this, hledger will parse both- ‘1,000’ and ‘1.000’ as 1. (Cf Amounts)-- 3. It declares how to render the commodity’s amounts when displaying- output - the decimal mark, any digit group marks, the number of- decimal places, symbol placement and so on. (Cf Commodity display- style)-- You will run into one of the problems solved by commodity directives-sooner or later, so we recommend using them, for robust and predictable-parsing and display.-- Generally you should put them at the top of your journal file (since-for function 2, they affect only following amounts, cf #793).-- A commodity directive is just the word ‘commodity’ followed by a-sample amount, like this:--;commodity SAMPLEAMOUNT--commodity $1000.00-commodity 1,000.0000 AAAA ; optional same-line comment-- It may also be written on multiple lines, and use the ‘format’-subdirective, as in Ledger. Note in this case the commodity symbol-appears twice; it must be the same in both places:--;commodity SYMBOL-; format SAMPLEAMOUNT--; display indian rupees with currency name on the left,-; thousands, lakhs and crores comma-separated,-; period as decimal point, and two decimal places.-commodity INR- format INR 1,00,00,000.00-- Other indented subdirectives are currently ignored.-- Remember that if the commodity symbol contains spaces, numbers, or-punctuation, it must be enclosed in double quotes (cf Commodity).-- The amount’s quantity does not matter; only the format is-significant. It must include a decimal mark - either a period or a-comma - followed by 0 or more decimal digits.-- A few more examples:--# number formats for $, EUR, INR and the no-symbol commodity:-commodity $1,000.00-commodity EUR 1.000,00-commodity INR 9,99,99,999.0-commodity 1 000 000.-- Note hledger normally uses banker’s rounding, so 0.5 displayed with-zero decimal digits is "0". (More at Commodity display style.)-- Even in the presence of commodity directives, the commodity display-style can still be overridden by supplying a command line option.--* Menu:--* Commodity error checking::---File: hledger.info, Node: Commodity error checking, Up: commodity directive--10.20.1 Commodity error checking-----------------------------------In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will-report an error if a commodity symbol is used that has not been declared-by a ‘commodity’ directive. This works similarly to account error-checking, see the notes there for more details.-- Note, this disallows amounts without a commodity symbol, because-currently it’s not possible (?) to declare the "no-symbol" commodity-with a directive. This is one exception for convenience: zero amounts-are always allowed to have no commodity symbol.---File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal--10.21 ‘decimal-mark’ directive-==============================--You can use a ‘decimal-mark’ directive - usually one per file, at the-top of the file - to declare which character represents a decimal mark-when parsing amounts in this file. It can look like--decimal-mark .-- or--decimal-mark ,-- This prevents any ambiguity when parsing numbers in the file, so we-recommend it, especially if the file contains digit group marks (eg-thousands separators).---File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal--10.22 ‘include’ directive-=========================--You can pull in the content of additional files by writing an include-directive, like this:--include FILEPATH-- Only journal files can include, and only journal, timeclock or-timedot files can be included (not CSV files, currently).-- If the file path does not begin with a slash, it is relative to the-current file’s folder.-- A tilde means home directory, eg: ‘include ~/main.journal’.-- The path may contain glob patterns to match multiple files, eg:-‘include *.journal’.-- There is limited support for recursive wildcards: ‘**/’ (the slash is-required) matches 0 or more subdirectories. It’s not super convenient-since you have to avoid include cycles and including directories, but-this can be done, eg: ‘include */**/*.journal’.-- The path may also be prefixed to force a specific file format,-overriding the file extension (as described in hledger.1 -> Input-files): ‘include timedot:~/notes/2020*.md’.---File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal--10.23 ‘P’ directive-===================--The ‘P’ directive declares a market price, which is a conversion rate-between two commodities on a certain date. This allows value reports to-convert amounts of one commodity to their value in another, on or after-that date. These prices are often obtained from a stock exchange,-cryptocurrency exchange, the or foreign exchange market.-- The format is:--P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT-- DATE is a simple date, COMMODITY1SYMBOL is the symbol of the-commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and-quantity) of commodity 2 that one unit of commodity 1 is worth on this-date. Examples:--# one euro was worth $1.35 from 2009-01-01 onward:-P 2009-01-01 € $1.35--# and $1.40 from 2010-01-01 onward:-P 2010-01-01 € $1.40-- The ‘-V’, ‘-X’ and ‘--value’ flags use these market prices to show-amount values in another commodity. See Valuation.---File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal--10.24 ‘payee’ directive-=======================--‘payee PAYEE NAME’-- This directive can be used to declare a limited set of payees which-may appear in transaction descriptions. The "payees" check will report-an error if any transaction refers to a payee that has not been-declared. Eg:--payee Whole Foods-- Any indented subdirectives are currently ignored.---File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal--10.25 ‘tag’ directive-=====================--‘tag TAGNAME’-- This directive can be used to declare a limited set of tag names-allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg:--tag item-id-- Any indented subdirectives are currently ignored.-- The "tags" check will report an error if any undeclared tag name is-used. It is quite easy to accidentally create a tag through normal use-of colons in comments(#comments]; if you want to prevent this, you can-declare and check your tags .---File: hledger.info, Node: Periodic transactions, Next: Other syntax, Prev: tag directive, Up: Journal--10.26 Periodic transactions-===========================--The ‘~’ directive declares recurring transactions. Such directives-allow hledger to generate temporary future transactions (visible in-reports, not in the journal file) to help with forecasting or budgeting.-- Periodic transactions can be a little tricky, so before you use them,-read this whole section, or at least these tips:-- 1. Two spaces accidentally added or omitted will cause you trouble -- read about this below.- 2. For troubleshooting, show the generated transactions with ‘hledger- print --forecast tag:generated’ or ‘hledger register --forecast- tag:generated’.- 3. Forecasted transactions will begin only after the last- non-forecasted transaction’s date.- 4. Forecasted transactions will end 6 months from today, by default.- See below for the exact start/end rules.- 5. period expressions can be tricky. Their documentation needs- improvement, but is worth studying.- 6. Some period expressions with a repeating interval must begin on a- natural boundary of that interval. Eg in ‘weekly from DATE’, DATE- must be a monday. ‘~ weekly from 2019/10/1’ (a tuesday) will give- an error.- 7. Other period expressions with an interval are automatically- expanded to cover a whole number of that interval. (This is done- to improve reports, but it also affects periodic transactions.- Yes, it’s a bit inconsistent with the above.) Eg: ‘~ every 10th- day of month from 2020/01’, which is equivalent to ‘~ every 10th- day of month from 2020/01/01’, will be adjusted to start on- 2019/12/10.--* Menu:--* Periodic rule syntax::-* Periodic rules and relative dates::-* Two spaces between period expression and description!::---File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions--10.26.1 Periodic rule syntax-------------------------------A periodic transaction rule looks like a normal journal entry, with the-date replaced by a tilde (‘~’) followed by a period expression-(mnemonic: ‘~’ looks like a recurring sine wave.):--# every first of month-~ monthly- expenses:rent $2000- assets:bank:checking--# every 15th of month in 2023's first quarter:-~ monthly from 2023-04-15 to 2023-06-16- expenses:utilities $400- assets:bank:checking-- The period expression is the same syntax used for specifying-multi-period reports, just interpreted differently; there, it specifies-report periods; here it specifies recurrence dates (the periods’ start-dates).---File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions--10.26.2 Periodic rules and relative dates--------------------------------------------Partial or relative dates (like ‘12/31’, ‘25’, ‘tomorrow’, ‘last week’,-‘next quarter’) are usually not recommended in periodic rules, since the-results will change as time passes. If used, they will be interpreted-relative to, in order of preference:-- 1. the first day of the default year specified by a recent ‘Y’- directive- 2. or the date specified with ‘--today’- 3. or the date on which you are running the report.-- They will not be affected at all by report period or forecast period-dates.---File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions--10.26.3 Two spaces between period expression and description!----------------------------------------------------------------If the period expression is followed by a transaction description, these-must be separated by *two or more spaces*. This helps hledger know-where the period expression ends, so that descriptions can not-accidentally alter their meaning, as in this example:--; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"-; ||-; vv-~ every 2 months in 2020, we will review- assets:bank:checking $1500- income:acme inc-- So,-- • Do write two spaces between your period expression and your- transaction description, if any.- • Don’t accidentally write two spaces in the middle of your period- expression.---File: hledger.info, Node: Other syntax, Prev: Periodic transactions, Up: Journal--10.27 Other syntax-==================--hledger journal format supports quite a few other features, mainly to-make interoperating with or converting from Ledger easier. Note some of-the features below are powerful and can be useful in special cases, but-in general, features in this section are considered less important or-even not recommended for most users. Downsides are mentioned to help-you decide if you want to use them.--* Menu:--* Auto postings::-* Balance assignments::-* Bracketed posting dates::-* D directive::-* apply account directive::-* Y directive::-* Secondary dates::-* Star comments::-* Valuation expressions::-* Virtual postings::-* Other Ledger directives::---File: hledger.info, Node: Auto postings, Next: Balance assignments, Up: Other syntax--10.27.1 Auto postings------------------------The ‘=’ directive declares a rule for automatically adding temporary-extra postings (visible in reports, not in the journal file) to all-transactions matched by a certain query, when you use the ‘--auto’ flag.-- Downsides: depending on generated data for your reports makes your-financial data less portable, less future-proof, and less trustworthy in-an audit. Also, because the feature is optional, other features like-balance assertions can break depending on whether it is on or off.-- An auto posting rule looks a bit like a transaction:--= QUERY- ACCOUNT AMOUNT- ...- ACCOUNT [AMOUNT]-- except the first line is an equals sign (mnemonic: ‘=’ suggests-matching), followed by a query (which matches existing postings), and-each "posting" line describes a posting to be generated, and the posting-amounts can be:-- • a normal amount with a commodity symbol, eg ‘$2’. This will be- used as-is.- • a number, eg ‘2’. The commodity symbol (if any) from the matched- posting will be added to this.- • a numeric multiplier, eg ‘*2’ (a star followed by a number N). The- matched posting’s amount (and total price, if any) will be- multiplied by N.- • a multiplier with a commodity symbol, eg ‘*$2’ (a star, number N,- and symbol S). The matched posting’s amount will be multiplied by- N, and its commodity symbol will be replaced with S.-- Any query term containing spaces must be enclosed in single or double-quotes, as on the command line. Eg, note the quotes around the second-query term below:--= expenses:groceries 'expenses:dining out'- (budget:funds:dining out) *-1-- Some examples:--; every time I buy food, schedule a dollar donation-= expenses:food- (liabilities:charity) $-1--; when I buy a gift, also deduct that amount from a budget envelope subaccount-= expenses:gifts- assets:checking:gifts *-1- assets:checking *1--2017/12/1- expenses:food $10- assets:checking--2017/12/14- expenses:gifts $20- assets:checking--$ hledger print --auto-2017-12-01- expenses:food $10- assets:checking- (liabilities:charity) $-1--2017-12-14- expenses:gifts $20- assets:checking- assets:checking:gifts -$20- assets:checking $20--* Menu:--* Auto postings and multiple files::-* Auto postings and dates::-* Auto postings and transaction balancing / inferred amounts / balance assertions::-* Auto posting tags::---File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings--10.27.1.1 Auto postings and multiple files-..........................................--An auto posting rule can affect any transaction in the current file, or-in any parent file or child file. Note, currently it will not affect-sibling files (when multiple ‘-f’/‘--file’ are used - see #1212).---File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings--10.27.1.2 Auto postings and dates-.................................--A posting date (or secondary date) in the matched posting, or (taking-precedence) a posting date in the auto posting rule itself, will also be-used in the generated posting.---File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings--10.27.1.3 Auto postings and transaction balancing / inferred-............................................................--amounts / balance assertions Currently, auto postings are added:-- • after missing amounts are inferred, and transactions are checked- for balancedness,- • but before balance assertions are checked.-- Note this means that journal entries must be balanced both before and-after auto postings are added. This changed in hledger 1.12+; see #893-for background.-- This also means that you cannot have more than one auto-posting with-a missing amount applied to a given transaction, as it will be unable to-infer amounts.---File: hledger.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings--10.27.1.4 Auto posting tags-...........................--Automated postings will have some extra tags:-- • ‘generated-posting:= QUERY’ - shows this was generated by an auto- posting rule, and the query- • ‘_generated-posting:= QUERY’ - a hidden tag, which does not appear- in hledger’s output. This can be used to match postings generated- "just now", rather than generated in the past and saved to the- journal.-- Also, any transaction that has been changed by auto posting rules-will have these tags added:-- • ‘modified:’ - this transaction was modified- • ‘_modified:’ - a hidden tag not appearing in the comment; this- transaction was modified "just now".---File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Prev: Auto postings, Up: Other syntax--10.27.2 Balance assignments------------------------------Ledger-style balance assignments are also supported. These are like-balance assertions, but with no posting amount on the left side of the-equals sign; instead it is calculated automatically so as to satisfy the-assertion. This can be a convenience during data entry, eg when setting-opening balances:--; starting a new journal, set asset account balances-2016/1/1 opening balances- assets:checking = $409.32- assets:savings = $735.24- assets:cash = $42- equity:opening balances-- or when adjusting a balance to reality:--; no cash left; update balance, record any untracked spending as a generic expense-2016/1/15- assets:cash = $0- expenses:misc-- The calculated amount depends on the account’s balance in the-commodity at that point (which depends on the previously-dated postings-of the commodity to that account since the last balance assertion or-assignment).-- Downsides: using balance assignments makes your journal less-explicit; to know the exact amount posted, you have to run hledger or do-the calculations yourself, instead of just reading it. Also balance-assignments’ forcing of balances can hide errors. These things make-your financial data less portable, less future-proof, and less-trustworthy in an audit.--* Menu:--* Balance assignments and prices::---File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments--10.27.2.1 Balance assignments and prices-........................................--A cost in a balance assignment will cause the calculated amount to have-that price attached:--2019/1/1- (a) = $1 @ €2--$ hledger print --explicit-2019-01-01- (a) $1 @ €2 = $1 @ €2---File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax--10.27.3 Bracketed posting dates----------------------------------For setting posting dates and secondary posting dates, Ledger’s-bracketed date syntax is also supported: ‘[DATE]’, ‘[DATE=DATE2]’ or-‘[=DATE2]’ in posting comments. hledger will attempt to parse any-square-bracketed sequence of the ‘0123456789/-.=’ characters in this-way. With this syntax, DATE infers its year from the transaction and-DATE2 infers its year from DATE.-- Downsides: another syntax to learn, redundant with hledger’s-‘date:’/‘date2:’ tags, and confusingly similar to Ledger’s lot date-syntax.---File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax--10.27.4 ‘D’ directive------------------------‘D AMOUNT’-- This directive sets a default commodity, to be used for any-subsequent commodityless amounts (ie, plain numbers) seen while parsing-the journal. This effect lasts until the next ‘D’ directive, or the end-of the journal.-- For compatibility/historical reasons, ‘D’ also acts like a-‘commodity’ directive (setting the commodity’s decimal mark for parsing-and display style for output). So its argument is not just a commodity-symbol, but a full amount demonstrating the style. The amount must-include a decimal mark (either period or comma). Eg:--; commodity-less amounts should be treated as dollars-; (and displayed with the dollar sign on the left, thousands separators and two decimal places)-D $1,000.00--1/1- a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00- b-- Interactions with other directives:-- For setting a commodity’s display style, a ‘commodity’ directive has-highest priority, then a ‘D’ directive.-- For detecting a commodity’s decimal mark during parsing,-‘decimal-mark’ has highest priority, then ‘commodity’, then ‘D’.-- For checking commodity symbols with the check command, a ‘commodity’-directive is required (‘hledger check commodities’ ignores ‘D’-directives).-- Downsides: omitting commodity symbols makes your financial data less-explicit, less portable, and less trustworthy in an audit. It is-usually an unsustainable shortcut; sooner or later you will want to-track multiple commodities. D is overloaded with functions redundant-with ‘commodity’ and ‘decimal-mark’. And it works differently from-Ledger’s ‘D’.---File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax--10.27.5 ‘apply account’ directive------------------------------------This directive sets a default parent account, which will be prepended to-all accounts in following entries, until an ‘end apply account’-directive or end of current file. Eg:--apply account home--2010/1/1- food $10- cash--end apply account-- is equivalent to:--2010/01/01- home:food $10- home:cash $-10-- ‘account’ directives are also affected, and so is any ‘include’d-content.-- Account names entered via hledger add or hledger-web are not-affected.-- Account aliases, if any, are applied after the parent account is-prepended.-- Downsides: this can make your financial data less explicit, less-portable, and less trustworthy in an audit.---File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax--10.27.6 ‘Y’ directive------------------------‘Y YEAR’-- or (deprecated backward-compatible forms):-- ‘year YEAR’ ‘apply year YEAR’-- The space is optional. This sets a default year to be used for-subsequent dates which don’t specify a year. Eg:--Y2009 ; set default year to 2009--12/15 ; equivalent to 2009/12/15- expenses 1- assets--year 2010 ; change default year to 2010--2009/1/30 ; specifies the year, not affected- expenses 1- assets--1/31 ; equivalent to 2010/1/31- expenses 1- assets-- Downsides: omitting the year (from primary transaction dates, at-least) makes your financial data less explicit, less portable, and less-trustworthy in an audit. Such dates can get separated from their-corresponding Y directive, eg when evaluating a region of the journal in-your editor. A missing Y directive makes reports dependent on today’s-date.---File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax--10.27.7 Secondary dates--------------------------A secondary date is written after the primary date, following an equals-sign. If the year is omitted, the primary date’s year is assumed. When-running reports, the primary (left) date is used by default, but with-the ‘--date2’ flag (or ‘--aux-date’ or ‘--effective’), the secondary-(right) date will be used instead.-- The meaning of secondary dates is up to you, but it’s best to follow-a consistent rule. Eg "primary = the bank’s clearing date, secondary =-date the transaction was initiated, if different".-- Downsides: makes your financial data more complicated, less portable,-and less trustworthy in an audit. Keeping the meaning of the two dates-consistent requires discipline, and you have to remember which reporting-mode is appropriate for a given report. Posting dates are simpler and-better.---File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax--10.27.8 Star comments------------------------Lines beginning with ‘*’ (star/asterisk) are also comment lines. This-feature allows Emacs users to insert org headings in their journal,-allowing them to fold/unfold/navigate it like an outline when viewed-with org mode.-- Downsides: another, unconventional comment syntax to learn.-Decreases your journal’s portability. And switching to Emacs org mode-just for folding/unfolding meant losing the benefits of ledger mode;-nowadays you can add outshine mode to ledger mode to get folding without-losing ledger mode’s features.---File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax--10.27.9 Valuation expressions--------------------------------Ledger allows a valuation function or value to be written in double-parentheses after an amount. hledger ignores these.---File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax--10.27.10 Virtual postings----------------------------A posting with parentheses around the account name is called a _virtual-posting_ or _unbalanced posting_, which means it is exempt from the-usual rule that a transaction’s postings must balance add up to zero.-- This is not part of double entry bookkeeping, so you might choose to-avoid this feature. Or you can use it sparingly for certain special-cases where it can be convenient. Eg, you could set opening balances-without using a balancing equity account:--2022-01-01 opening balances- (assets:checking) $1000- (assets:savings) $2000-- A posting with brackets around the account name is called a _balanced-virtual posting_. The balanced virtual postings in a transaction must-add up to zero (separately from other postings). Eg:--2022-01-01 buy food with cash, update budget envelope subaccounts, & something else- assets:cash $-10 ; <- these balance each other- expenses:food $7 ; <-- expenses:food $3 ; <-- [assets:checking:budget:food] $-10 ; <- and these balance each other- [assets:checking:available] $10 ; <-- (something:else) $5 ; <- this is not required to balance-- Postings whose account names are neither parenthesised nor bracketed-are called _real postings_. You can exclude virtual postings from-reports with the ‘-R/--real’ flag or a ‘real:1’ query.-- Downsides: violates double entry bookkeeping, can be used to avoid-figuring out correct entries, makes your financial data less portable-and less trustworthy in an audit.---File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax--10.27.11 Other Ledger directives-----------------------------------These other Ledger directives are currently accepted but ignored. This-allows hledger to read more Ledger files, but be aware that hledger’s-reports may differ from Ledger’s if you use these.--apply fixed COMM AMT-apply tag TAG-assert EXPR-bucket / A ACCT-capture ACCT REGEX-check EXPR-define VAR=EXPR-end apply fixed-end apply tag-end apply year-end tag-eval / expr EXPR-python- PYTHONCODE-tag NAME-value EXPR---command-line-flags-- See also https://hledger.org/ledger.html for a detailed-hledger/Ledger syntax comparison.---File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top--11 CSV-******--hledger can read CSV files (Character Separated Value - usually comma,-semicolon, or tab) containing dated records, automatically converting-each record into a transaction.-- (To learn about _writing_ CSV, see CSV output.)-- For best error messages when reading CSV/TSV/SSV files, make sure-they have a corresponding ‘.csv’, ‘.tsv’ or ‘.ssv’ file extension or use-a hledger file prefix (see File Extension below).-- Each CSV file must be described by a corresponding _rules file_.-This contains rules describing the CSV data (header line, fields layout,-date format etc.), how to construct hledger transactions from it, and-how to categorise transactions based on description or other attributes.-- By default hledger looks for a rules file named like the CSV file-with an extra ‘.rules’ extension, in the same directory. Eg when asked-to read ‘foo/FILE.csv’, hledger looks for ‘foo/FILE.csv.rules’. You can-specify a different rules file with the ‘--rules-file’ option. If no-rules file is found, hledger will create a sample rules file, which-you’ll need to adjust.-- At minimum, the rules file must identify the date and amount fields,-and often it also specifies the date format and how many header lines-there are. Here’s a simple CSV file and a rules file for it:--Date, Description, Id, Amount-12/11/2019, Foo, 123, 10.23--# basic.csv.rules-skip 1-fields date, description, , amount-date-format %d/%m/%Y--$ hledger print -f basic.csv-2019-11-12 Foo- expenses:unknown 10.23- income:unknown -10.23-- There’s an introductory Importing CSV data tutorial on hledger.org,-and more CSV rules examples below, and a larger collection at-https://github.com/simonmichael/hledger/tree/master/examples/csv.--* Menu:--* CSV rules cheatsheet::-* separator::-* skip::-* date-format::-* timezone::-* newest-first::-* intra-day-reversed::-* decimal-mark::-* fields list::-* Field assignment::-* Field names::-* if block::-* Matchers::-* if table::-* balance-type::-* include::-* Working with CSV::-* CSV rules examples::---File: hledger.info, Node: CSV rules cheatsheet, Next: separator, Up: CSV--11.1 CSV rules cheatsheet-=========================--The following kinds of rule can appear in the rules file, in any order.-(Blank lines and lines beginning with ‘#’ or ‘;’ or ‘*’ are ignored.)--*‘separator’* declare the field separator, instead of- relying on file extension-*‘skip’* skip one or more header lines at start of file-*‘date-format’* declare how to parse CSV dates/date-times-*‘timezone’* declare the time zone of ambiguous CSV- date-times-*‘newest-first’* improve txn order when: there are multiple- records, newest first, all with the same date-*‘intra-day-reversed’* improve txn order when: same-day txns are in- opposite order to the overall file-*‘decimal-mark’* declare the decimal mark used in CSV amounts,- when ambiguous-*‘fields’ list* name CSV fields for easy reference, and- optionally assign their values to hledger- fields-*Field assignment* assign a CSV value or interpolated text value- to a hledger field-*‘if’ block* conditionally assign values to hledger fields,- or ‘skip’ a record or ‘end’ (skip rest of- file)-*‘if’ table* conditionally assign values to hledger fields,- using compact syntax-*‘balance-type’* select which type of balance- assertions/assignments to generate-*‘include’* inline another CSV rules file-- Working with CSV tips can be found below, including How CSV rules are-evaluated.---File: hledger.info, Node: separator, Next: skip, Prev: CSV rules cheatsheet, Up: CSV--11.2 ‘separator’-================--You can use the ‘separator’ rule to read other kinds of-character-separated data. The argument is any single separator-character, or the words ‘tab’ or ‘space’ (case insensitive). Eg, for-comma-separated values (CSV):--separator ,-- or for semicolon-separated values (SSV):--separator ;-- or for tab-separated values (TSV):--separator TAB-- If the input file has a ‘.csv’, ‘.ssv’ or ‘.tsv’ file extension (or a-‘csv:’, ‘ssv:’, ‘tsv:’ prefix), the appropriate separator will be-inferred automatically, and you won’t need this rule.---File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV--11.3 ‘skip’-===========--skip N-- The word ‘skip’ followed by a number (or no number, meaning 1) tells-hledger to ignore this many non-empty lines at the start of the input-data. (Empty/blank lines are skipped automatically, so you don’t need-to count those.) You’ll need this whenever your CSV data contains-header lines. Header lines skipped in this way are ignored, and not-parsed as CSV.-- ‘skip’ can also be used inside if blocks (described below), to skip-individual data records. Note records skipped in this way are still-required to be valid CSV, even though otherwise ignored.---File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV--11.4 ‘date-format’-==================--date-format DATEFMT-- This is a helper for the ‘date’ (and ‘date2’) fields. If your CSV-dates are not formatted like ‘YYYY-MM-DD’, ‘YYYY/MM/DD’ or ‘YYYY.MM.DD’,-you’ll need to add a date-format rule describing them with a-strptime-style date parsing pattern - see-https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime.-The pattern must parse the CSV date value completely. Some examples:--# MM/DD/YY-date-format %m/%d/%y--# D/M/YYYY-# The - makes leading zeros optional.-date-format %-d/%-m/%Y--# YYYY-Mmm-DD-date-format %Y-%h-%d--# M/D/YYYY HH:MM AM some other junk-# Note the time and junk must be fully parsed, though only the date is used.-date-format %-m/%-d/%Y %l:%M %p some other junk---File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV--11.5 ‘timezone’-===============--timezone TIMEZONE-- When CSV contains date-times that are implicitly in some time zone-other than yours, but containing no explicit time zone information, you-can use this rule to declare the CSV’s native time zone, which helps-prevent off-by-one dates.-- When the CSV date-times do contain time zone information, you don’t-need this rule; instead, use ‘%Z’ in ‘date-format’ (or ‘%z’, ‘%EZ’,-‘%Ez’; see the formatTime link above).-- In either of these cases, hledger will do a time-zone-aware-conversion, localising the CSV date-times to your current system time-zone. If you prefer to localise to some other time zone, eg for-reproducibility, you can (on unix at least) set the output timezone with-the TZ environment variable, eg:--$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv-- ‘timezone’ currently does not understand timezone names, except-"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".-For others, use numeric format: +HHMM or -HHMM.---File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV--11.6 ‘newest-first’-===================--hledger tries to ensure that the generated transactions will be ordered-chronologically, including intra-day transactions. Usually it can-auto-detect how the CSV records are ordered. But if it encounters CSV-where all records are on the same date, it assumes that the records are-oldest first. If in fact the CSV’s records are normally newest first,-like:--2022-10-01, txn 3...-2022-10-01, txn 2...-2022-10-01, txn 1...-- you can add the ‘newest-first’ rule to help hledger generate the-transactions in correct order.--# same-day CSV records are newest first-newest-first---File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV--11.7 ‘intra-day-reversed’-=========================--CSV records for each day are sometimes ordered in reverse compared to-the overall date order. Eg, here dates are newest first, but the-transactions on each date are oldest first:--2022-10-02, txn 3...-2022-10-02, txn 4...-2022-10-01, txn 1...-2022-10-01, txn 2...-- In this situation, add the ‘intra-day-reversed’ rule, and hledger-will compensate, improving the order of transactions.--# transactions within each day are reversed with respect to the overall date order-intra-day-reversed---File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV--11.8 ‘decimal-mark’-===================--decimal-mark .-- or:--decimal-mark ,-- hledger automatically accepts either period or comma as a decimal-mark when parsing numbers (cf Amounts). However if any numbers in the-CSV contain digit group marks, such as thousand-separating commas, you-should declare the decimal mark explicitly with this rule, to avoid-misparsed numbers.---File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV--11.9 ‘fields’ list-==================--fields FIELDNAME1, FIELDNAME2, ...-- A fields list (the word ‘fields’ followed by comma-separated field-names) is optional, but convenient. It does two things:-- 1. It names the CSV field in each column. This can be convenient if- you are referencing them in other rules, so you can say- ‘%SomeField’ instead of remembering ‘%13’.-- 2. Whenever you use one of the special hledger field names (described- below), it assigns the CSV value in this position to that hledger- field. This is the quickest way to populate hledger’s fields and- build a transaction.-- Here’s an example that says "use the 1st, 2nd and 4th fields as the-transaction’s date, description and amount; name the last two fields for-later reference; and ignore the others":--fields date, description, , amount, , , somefield, anotherfield-- In a fields list, the separator is always comma; it is unrelated to-the CSV file’s separator. Also:-- • There must be least two items in the list (at least one comma).- • Field names may not contain spaces. Spaces before/after field- names are optional.- • Field names may contain ‘_’ (underscore) or ‘-’ (hyphen).- • Fields you don’t care about can be given a dummy name or an empty- name.-- If the CSV contains column headings, it’s convenient to use these for-your field names, suitably modified (eg lower-cased with spaces replaced-by underscores).-- Sometimes you may want to alter a CSV field name to avoid assigning-to a hledger field with the same name. Eg you could call the CSV’s-"balance" field ‘balance_’ to avoid directly setting hledger’s ‘balance’-field (and generating a balance assertion).---File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV--11.10 Field assignment-======================--HLEDGERFIELD FIELDVALUE-- Field assignments are the more flexible way to assign CSV values to-hledger fields. They can be used instead of or in addition to a fields-list (see above).-- To assign a value to a hledger field, write the field name (any of-the standard hledger field/pseudo-field names, defined below), a space,-followed by a text value on the same line. This text value may-interpolate CSV fields, referenced by their 1-based position in the CSV-record (‘%N’), or by the name they were given in the fields list-(‘%CSVFIELD’).-- Some examples:--# set the amount to the 4th CSV field, with " USD" appended-amount %4 USD--# combine three fields to make a comment, containing note: and date: tags-comment note: %somefield - %anotherfield, date: %1-- Tips:-- • Interpolation strips outer whitespace (so a CSV value like ‘" 1 "’- becomes ‘1’ when interpolated) (#1051).- • Interpolations always refer to a CSV field - you can’t interpolate- a hledger field. (See Referencing other fields below).---File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV--11.11 Field names-=================--Note the two kinds of field names mentioned here, and used only in-hledger CSV rules files:-- 1. *CSV field names* (‘CSVFIELD’ in these docs): you can optionally- name the CSV columns for easy reference (since hledger doesn’t yet- automatically recognise column headings in a CSV file), by writing- arbitrary names in a ‘fields’ list, eg:-- fields When, What, Some_Id, Net, Total, Foo, Bar-- 2. Special *hledger field names* (‘HLEDGERFIELD’ in these docs): you- must set at least some of these to generate the hledger transaction- from a CSV record, by writing them as the left hand side of a field- assignment, eg:-- date %When- code %Some_Id- description %What- comment %Foo %Bar- amount1 $ %Total-- or directly in a ‘fields’ list:-- fields date, description, code, , amount1, Foo, Bar- currency $- comment %Foo %Bar-- Here are all the special hledger field names available, and what-happens when you assign values to them:--* Menu:--* date field::-* date2 field::-* status field::-* code field::-* description field::-* comment field::-* account field::-* amount field::-* currency field::-* balance field::---File: hledger.info, Node: date field, Next: date2 field, Up: Field names--11.11.1 date field---------------------Assigning to ‘date’ sets the transaction date.---File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names--11.11.2 date2 field----------------------‘date2’ sets the transaction’s secondary date, if any.---File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names--11.11.3 status field-----------------------‘status’ sets the transaction’s status, if any.---File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names--11.11.4 code field---------------------‘code’ sets the transaction’s code, if any.---File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names--11.11.5 description field----------------------------‘description’ sets the transaction’s description, if any.---File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names--11.11.6 comment field------------------------‘comment’ sets the transaction’s comment, if any.-- ‘commentN’, where N is a number, sets the Nth posting’s comment.-- You can assign multi-line comments by writing literal ‘\n’ in the-code. A comment starting with ‘\n’ will begin on a new line.-- Comments can contain tags, as usual.---File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names--11.11.7 account field------------------------Assigning to ‘accountN’, where N is 1 to 99, sets the account name of-the Nth posting, and causes that posting to be generated.-- Most often there are two postings, so you’ll want to set ‘account1’-and ‘account2’. Typically ‘account1’ is associated with the CSV file,-and is set once with a top-level assignment, while ‘account2’ is set-based on each transaction’s description, in conditional rules.-- If a posting’s account name is left unset but its amount is set (see-below), a default account name will be chosen (like "expenses:unknown"-or "income:unknown").---File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names--11.11.8 amount field-----------------------There are several "amount" field name variants, useful for different-situations:-- • ‘amountN’ sets the amount of the Nth posting, and causes that- posting to be generated. By assigning to ‘amount1’, ‘amount2’, ...- etc. you can generate up to 99 postings. Posting numbers don’t- have to be consecutive; in certain situations using a high number- might be helpful to influence the layout of postings.-- • ‘amountN-in’ and ‘amountN-out’ should be used instead, as a pair,- when and only when the amount must be obtained from two CSV fields.- Eg when the CSV has separate Debit and Credit fields instead of a- single Amount field. Note:-- • Don’t think "-in is for the first posting and -out is for the- second posting" - that’s not correct. Think: "‘amountN-in’- and ‘amountN-out’ together detect the amount for posting N, by- inspecting two CSV fields at once."- • hledger assumes both CSV fields are unsigned, and will- automatically negate the -out value.- • It also expects that at least one of the values is empty or- zero, so it knows which one to ignore. If that’s not the case- you’ll need an if rule (see Setting amounts below).-- • ‘amount’, with no posting number (and similarly, ‘amount-in’ and- ‘amount-out’ with no number) are an older syntax. We keep them for- backwards compatibility, and because they have special behaviour- that is sometimes convenient:-- • They set the amount of posting 1 and (negated) the amount of- posting 2.- • Posting 2’s amount will be converted to cost if it has a cost- price.- • Any of the newer rules for posting 1 or 2 (like ‘amount1’, or- ‘amount2-in’ and ‘amount2-out’) will take precedence. This- allows incrementally migrating old rules files to the new- syntax.-- There’s more to say about amount-setting that doesn’t fit here;-please see also "Setting amounts" below.---File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names--11.11.9 currency field-------------------------‘currency’ sets a currency symbol, to be prepended to all postings’-amounts. You can use this if the CSV amounts do not have a currency-symbol, eg if it is in a separate column.-- ‘currencyN’ prepends a currency symbol to just the Nth posting’s-amount.---File: hledger.info, Node: balance field, Prev: currency field, Up: Field names--11.11.10 balance field-------------------------‘balanceN’ sets a balance assertion amount (or if the posting amount is-left empty, a balance assignment) on posting N.-- ‘balance’ is a compatibility spelling for hledger <1.17; it is-equivalent to ‘balance1’.-- You can adjust the type of assertion/assignment with the-‘balance-type’ rule (see below).-- See Tips below for more about setting amounts and currency.---File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV--11.12 ‘if’ block-================--Rules can be applied conditionally, depending on patterns in the CSV-data. This allows flexibility; in particular, it is how you can-categorise transactions, selecting an appropriate account name based on-their description (for example). There are two ways to write-conditional rules: "if blocks", described here, and "if tables",-described below.-- An if block is the word ‘if’ and one or more "matcher" expressions-(can be a word or phrase), one per line, starting either on the same or-next line; followed by one or more indented rules. Eg,--if MATCHER- RULE-- or--if-MATCHER-MATCHER-MATCHER- RULE- RULE-- If any of the matchers succeeds, all of the indented rules will be-applied. They are usually field assignments, but the following special-rules may also be used within an if block:-- • ‘skip’ - skips the matched CSV record (generating no transaction- from it)- • ‘end’ - skips the rest of the current CSV file.-- Some examples:--# if the record contains "groceries", set account2 to "expenses:groceries"-if groceries- account2 expenses:groceries--# if the record contains any of these phrases, set account2 and a transaction comment as shown-if-monthly service fee-atm transaction fee-banking thru software- account2 expenses:business:banking- comment XXX deductible ? check it--# if an empty record is seen (assuming five fields), ignore the rest of the CSV file-if ,,,,- end---File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV--11.13 Matchers-==============--There are two kinds:-- 1. A record matcher is a word or single-line text fragment or regular- expression (‘REGEX’), which hledger will try to match- case-insensitively anywhere within the CSV record.- Eg: ‘whole foods’-- 2. A field matcher is preceded with a percent sign and CSV field name- (‘%CSVFIELD REGEX’). hledger will try to match these just within- the named CSV field.- Eg: ‘%date 2023’-- The regular expression is (as usual in hledger) a POSIX extended-regular expression, that also supports GNU word boundaries (‘\b’, ‘\B’,-‘\<’, ‘\>’), and nothing else. If you have trouble, see "Regular-expressions" in the hledger manual-(https://hledger.org/hledger.html#regular-expressions).-- With record matchers, it’s important to know that the record matched-is not the original CSV record, but a modified one: separators will be-converted to commas, and enclosing double quotes (but not enclosing-whitespace) are removed. So for example, when reading an SSV file, if-the original record was:--2020-01-01; "Acme, Inc."; 1,000-- the regex would see, and try to match, this modified record text:--2020-01-01,Acme, Inc., 1,000-- When an if block has multiple matchers, they are combined as follows:-- • By default they are OR’d (any one of them can match)- • When a matcher is preceded by ampersand (‘&’) it will be AND’ed- with the previous matcher (both of them must match).-- There’s not yet an easy syntax to negate a matcher.---File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV--11.14 ‘if’ table-================--"if tables" are an alternative to if blocks; they can express many-matchers and field assignments in a more compact tabular format, like-this:--if,HLEDGERFIELD1,HLEDGERFIELD2,...-MATCHERA,VALUE1,VALUE2,...-MATCHERB,VALUE1,VALUE2,...-MATCHERC,VALUE1,VALUE2,...-<empty line>-- The first character after ‘if’ is taken to be the separator for the-rest of the table. It should be a non-alphanumeric character like ‘,’-or ‘|’ that does not appear anywhere else in the table. (Note: it is-unrelated to the CSV file’s separator.) Whitespace can be used in the-matcher lines for readability, but not in the if line currently. The-table must be terminated by an empty line (or end of file). Each line-must contain the same number of separators; empty values are allowed.-- The above means: try all of the matchers; whenever a matcher-succeeds, assign all of the values on that line to the corresponding-hledger fields; later lines can overrider earlier ones. It is-equivalent to this sequence of if blocks:--if MATCHERA- HLEDGERFIELD1 VALUE1- HLEDGERFIELD2 VALUE2- ...--if MATCHERB- HLEDGERFIELD1 VALUE1- HLEDGERFIELD2 VALUE2- ...--if MATCHERC- HLEDGERFIELD1 VALUE1- HLEDGERFIELD2 VALUE2- ...-- Example:--if,account2,comment-atm transaction fee,expenses:business:banking,deductible? check it-%description groceries,expenses:groceries,-2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out---File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV--11.15 ‘balance-type’-====================--Balance assertions generated by assigning to balanceN are of the simple-‘=’ type by default, which is a single-commodity, subaccount-excluding-assertion. You may find the subaccount-including variants more useful,-eg if you have created some virtual subaccounts of checking to help with-budgeting. You can select a different type of assertion with the-‘balance-type’ rule:--# balance assertions will consider all commodities and all subaccounts-balance-type ==*-- Here are the balance assertion types for quick reference:--= single commodity, exclude subaccounts-=* single commodity, include subaccounts-== multi commodity, exclude subaccounts-==* multi commodity, include subaccounts---File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV--11.16 ‘include’-===============--include RULESFILE-- This includes the contents of another CSV rules file at this point.-‘RULESFILE’ is an absolute file path or a path relative to the current-file’s directory. This can be useful for sharing common rules between-several rules files, eg:--# someaccount.csv.rules--## someaccount-specific rules-fields date,description,amount-account1 assets:someaccount-account2 expenses:misc--## common rules-include categorisation.rules---File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV--11.17 Working with CSV-======================--Some tips:--* Menu:--* Rapid feedback::-* Valid CSV::-* File Extension::-* Reading CSV from standard input::-* Reading multiple CSV files::-* Valid transactions::-* Deduplicating importing::-* Setting amounts::-* Amount signs::-* Setting currency/commodity::-* Amount decimal places::-* Referencing other fields::-* How CSV rules are evaluated::-* Well factored rules::---File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV--11.17.1 Rapid feedback-------------------------It’s a good idea to get rapid feedback while creating/troubleshooting-CSV rules. Here’s a good way, using entr from eradman.com/entrproject:--$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'-- A desc: query (eg) is used to select just one, or a few, transactions-of interest. "bash -c" is used to run multiple commands, so we can echo-a separator each time the command re-runs, making it easier to read the-output.---File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV--11.17.2 Valid CSV--------------------Note that hledger will only accept valid CSV conforming to RFC 4180, and-equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab-as separators). This means, eg:-- • Values may be enclosed in double quotes, or not. Enclosing in- single quotes is not allowed. (Eg ‘'A','B'’ is rejected.)- • When values are enclosed in double quotes, spaces outside the- quotes are not allowed. (Eg ‘"A", "B"’ is rejected.)- • When values are not enclosed in quotes, they may not contain double- quotes. (Eg ‘A"A, B’ is rejected.)-- If your CSV/SSV/TSV is not valid in this sense, you’ll need to-transform it before reading with hledger. Try using sed, or a more-permissive CSV parser like python’s csv lib.---File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV--11.17.3 File Extension-------------------------To help hledger choose the CSV file reader and show the right error-messages (and choose the right field separator character by default),-it’s best if CSV/SSV/TSV files are named with a ‘.csv’, ‘.ssv’ or ‘.tsv’-filename extension. (More about this at Data formats.)-- When reading files with the "wrong" extension, you can ensure the CSV-reader (and the default field separator) by prefixing the file path with-‘csv:’, ‘ssv:’ or ‘tsv:’: Eg:--$ hledger -f ssv:foo.dat print-- You can also override the default field separator with a separator-rule if needed.---File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV--11.17.4 Reading CSV from standard input------------------------------------------You’ll need the file format prefix when reading CSV from stdin also,-since hledger assumes journal format by default. Eg:--$ cat foo.dat | hledger -f ssv:- print---File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Reading CSV from standard input, Up: Working with CSV--11.17.5 Reading multiple CSV files-------------------------------------If you use multiple ‘-f’ options to read multiple CSV files at once,-hledger will look for a correspondingly-named rules file for each CSV-file. But if you use the ‘--rules-file’ option, that rules file will be-used for all the CSV files.---File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Working with CSV--11.17.6 Valid transactions-----------------------------After reading a CSV file, hledger post-processes and validates the-generated journal entries as it would for a journal file - balancing-them, applying balance assignments, and canonicalising amount styles.-Any errors at this stage will be reported in the usual way, displaying-the problem entry.-- There is one exception: balance assertions, if you have generated-them, will not be checked, since normally these will work only when the-CSV data is part of the main journal. If you do need to check balance-assertions generated from CSV right away, pipe into another hledger:--$ hledger -f file.csv print | hledger -f- print---File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV--11.17.7 Deduplicating, importing-----------------------------------When you download a CSV file periodically, eg to get your latest bank-transactions, the new file may overlap with the old one, containing some-of the same records.-- The import command will (a) detect the new transactions, and (b)-append just those transactions to your main journal. It is idempotent,-so you don’t have to remember how many times you ran it or with which-version of the CSV. (It keeps state in a hidden ‘.latest.FILE.csv’-file.) This is the easiest way to import CSV data. Eg:--# download the latest CSV files, then run this command.-# Note, no -f flags needed here.-$ hledger import *.csv [--dry]-- This method works for most CSV files. (Where records have a stable-chronological order, and new records appear only at the new end.)-- A number of other tools and workflows, hledger-specific and-otherwise, exist for converting, deduplicating, classifying and managing-CSV data. See:-- • https://hledger.org/cookbook.html#setups-and-workflows- • https://plaintextaccounting.org -> data import/conversion---File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV--11.17.8 Setting amounts--------------------------Continuing from amount field above, here are more tips on handling-various amount-setting situations:-- 1. *If the amount is in a single CSV field:*-- a. *If its sign indicates direction of flow:*- Assign it to ‘amountN’, to set the Nth posting’s amount. N is- usually 1 or 2 but can go up to 99.-- b. *If another field indicates direction of flow:*- Use one or more conditional rules to set the appropriate- amount sign. Eg:-- # assume a withdrawal unless Type contains "deposit":- amount1 -%Amount- if %Type deposit- amount1 %Amount-- 2. *If the amount is in one of two CSV fields (eg Debit and Credit):*-- a. *If both fields are unsigned:*- Assign the fields to ‘amountN-in’ and ‘amountN-out’. This- sets posting N’s amount to whichever of these has a non-zero- value. If it’s the -out value, the amount will be negated.-- b. *If either field is signed:*- Use a conditional rule to flip the sign when needed. Eg- below, the -out value already has a minus sign so we undo- hledger’s automatic negating by negating once more (but only- if the field is non-empty, so that we don’t leave a minus sign- by itself):-- fields date, description, amount1-in, amount1-out- if %amount1-out [1-9]- amount1-out -%amount1-out-- c. *If both fields can contain a non-zero value (or both can be- empty):*- The -in/-out rules normally choose the value which is- non-zero/non-empty. Some value pairs can be ambiguous, such- as ‘1’ and ‘none’. For such cases, use conditional rules to- help select the amount. Eg, to handle the above you could- select the value containing non-zero digits:-- fields date, description, in, out- if %in [1-9]- amount1 %in- if %out [1-9]- amount1 %out-- 3. *If you want posting 2’s amount converted to cost:*- Use the unnumbered ‘amount’ (or ‘amount-in’ and ‘amount-out’)- syntax.-- 4. *If the CSV has only balance amounts, not transaction amounts:*- Assign to ‘balanceN’, to set a balance assignment on the Nth- posting, causing the posting’s amount to be calculated- automatically. ‘balance’ with no number is equivalent to- ‘balance1’. In this situation hledger is more likely to guess the- wrong default account name, so you may need to set that explicitly.---File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV--11.17.9 Amount signs-----------------------There is some special handling for amount signs, to simplify parsing and-sign-flipping:-- • *If an amount value begins with a plus sign:*- that will be removed: ‘+AMT’ becomes ‘AMT’-- • *If an amount value is parenthesised:*- it will be de-parenthesised and sign-flipped: ‘(AMT)’ becomes- ‘-AMT’-- • *If an amount value has two minus signs (or two sets of- parentheses, or a minus sign and parentheses):*- they cancel out and will be removed: ‘--AMT’ or ‘-(AMT)’ becomes- ‘AMT’-- • *If an amount value contains just a sign (or just a set of- parentheses):*- that is removed, making it an empty value. ‘"+"’ or ‘"-"’ or- ‘"()"’ becomes ‘""’.---File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV--11.17.10 Setting currency/commodity--------------------------------------If the currency/commodity symbol is included in the CSV’s amount-field(s):--2020-01-01,foo,$123.00-- you don’t have to do anything special for the commodity symbol, it-will be assigned as part of the amount. Eg:--fields date,description,amount--2020-01-01 foo- expenses:unknown $123.00- income:unknown $-123.00-- If the currency is provided as a separate CSV field:--2020-01-01,foo,USD,123.00-- You can assign that to the ‘currency’ pseudo-field, which has the-special effect of prepending itself to every amount in the transaction-(on the left, with no separating space):--fields date,description,currency,amount--2020-01-01 foo- expenses:unknown USD123.00- income:unknown USD-123.00-- Or, you can use a field assignment to construct the amount yourself,-with more control. Eg to put the symbol on the right, and separated by-a space:--fields date,description,cur,amt-amount %amt %cur--2020-01-01 foo- expenses:unknown 123.00 USD- income:unknown -123.00 USD-- Note we used a temporary field name (‘cur’) that is not ‘currency’ --that would trigger the prepending effect, which we don’t want here.---File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV--11.17.11 Amount decimal places---------------------------------Like amounts in a journal file, the amounts generated by CSV rules like-‘amount1’ influence commodity display styles, such as the number of-decimal places displayed in reports.-- The original amounts as written in the CSV file do not affect display-style (because we don’t yet reliably know their commodity).---File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV--11.17.12 Referencing other fields------------------------------------In field assignments, you can interpolate only CSV fields, not hledger-fields. In the example below, there’s both a CSV field and a hledger-field named amount1, but %amount1 always means the CSV field, not the-hledger field:--# Name the third CSV field "amount1"-fields date,description,amount1--# Set hledger's amount1 to the CSV amount1 field followed by USD-amount1 %amount1 USD--# Set comment to the CSV amount1 (not the amount1 assigned above)-comment %amount1-- Here, since there’s no CSV amount1 field, %amount1 will produce a-literal "amount1":--fields date,description,csvamount-amount1 %csvamount USD-# Can't interpolate amount1 here-comment %amount1-- When there are multiple field assignments to the same hledger field,-only the last one takes effect. Here, comment’s value will be be B, or-C if "something" is matched, but never A:--comment A-comment B-if something- comment C---File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV--11.17.13 How CSV rules are evaluated---------------------------------------Here’s how to think of CSV rules being evaluated (if you really need-to). First,-- • ‘include’ - all includes are inlined, from top to bottom, depth- first. (At each include point the file is inlined and scanned for- further includes, recursively, before proceeding.)-- Then "global" rules are evaluated, top to bottom. If a rule is-repeated, the last one wins:-- • ‘skip’ (at top level)- • ‘date-format’- • ‘newest-first’- • ‘fields’ - names the CSV fields, optionally sets up initial- assignments to hledger fields-- Then for each CSV record in turn:-- • test all ‘if’ blocks. If any of them contain a ‘end’ rule, skip- all remaining CSV records. Otherwise if any of them contain a- ‘skip’ rule, skip that many CSV records. If there are multiple- matched ‘skip’ rules, the first one wins.- • collect all field assignments at top level and in matched ‘if’- blocks. When there are multiple assignments for a field, keep only- the last one.- • compute a value for each hledger field - either the one that was- assigned to it (and interpolate the %CSVFIELD references), or a- default- • generate a hledger transaction (journal entry) from these values.-- This is all part of the CSV reader, one of several readers hledger-can use to parse input files. When all files have been read-successfully, the transactions are passed as input to whichever hledger-command the user specified.---File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV--11.17.14 Well factored rules-------------------------------Some things than can help reduce duplication and complexity in rules-files:-- • Extracting common rules usable with multiple CSV files into a- ‘common.rules’, and adding ‘include common.rules’ to each CSV’s- rules file.-- • Splitting if blocks into smaller if blocks, extracting the- frequently used parts.---File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV--11.18 CSV rules examples-========================--* Menu:--* Bank of Ireland::-* Coinbase::-* Amazon::-* Paypal::---File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples--11.18.1 Bank of Ireland--------------------------Here’s a CSV with two amount fields (Debit and Credit), and a balance-field, which we can use to add balance assertions, which is not-necessary but provides extra error checking:--Date,Details,Debit,Credit,Balance-07/12/2012,LODGMENT 529898,,10.0,131.21-07/12/2012,PAYMENT,5,,126--# bankofireland-checking.csv.rules--# skip the header line-skip--# name the csv fields, and assign some of them as journal entry fields-fields date, description, amount-out, amount-in, balance--# We generate balance assertions by assigning to "balance"-# above, but you may sometimes need to remove these because:-#-# - the CSV balance differs from the true balance,-# by up to 0.0000000000005 in my experience-#-# - it is sometimes calculated based on non-chronological ordering,-# eg when multiple transactions clear on the same day--# date is in UK/Ireland format-date-format %d/%m/%Y--# set the currency-currency EUR--# set the base account for all txns-account1 assets:bank:boi:checking--$ hledger -f bankofireland-checking.csv print-2012-12-07 LODGMENT 529898- assets:bank:boi:checking EUR10.0 = EUR131.2- income:unknown EUR-10.0--2012-12-07 PAYMENT- assets:bank:boi:checking EUR-5.0 = EUR126.0- expenses:unknown EUR5.0-- The balance assertions don’t raise an error above, because we’re-reading directly from CSV, but they will be checked if these entries are-imported into a journal file.---File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples--11.18.2 Coinbase-------------------A simple example with some CSV from Coinbase. The spot price is-recorded using cost notation. The legacy ‘amount’ field name-conveniently sets amount 2 (posting 2’s amount) to the total cost.--# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes-# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"--# coinbase.csv.rules-skip 1-fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes-date %Timestamp-date-format %Y-%m-%dT%T%Z-description %Notes-account1 assets:coinbase:cc-amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency--$ hledger print -f coinbase.csv-2021-12-30 Received 100.00 USDC from an external account- assets:coinbase:cc 100 USDC @ 0.740000 GBP- income:unknown -74.000000 GBP---File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples--11.18.3 Amazon-----------------Here we convert amazon.com order history, and use an if block to-generate a third posting if there’s a fee. (In practice you’d probably-get this data from your bank instead, but it’s an example.)--"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"-"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"-"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"--# amazon-orders.csv.rules--# skip one header line-skip 1--# name the csv fields, and assign the transaction's date, amount and code.-# Avoided the "status" and "amount" hledger field names to prevent confusion.-fields date, _, toorfrom, name, amzstatus, amzamount, fees, code--# how to parse the date-date-format %b %-d, %Y--# combine two fields to make the description-description %toorfrom %name--# save the status as a tag-comment status:%amzstatus--# set the base account for all transactions-account1 assets:amazon-# leave amount1 blank so it can balance the other(s).-# I'm assuming amzamount excludes the fees, don't remember--# set a generic account2-account2 expenses:misc-amount2 %amzamount-# and maybe refine it further:-#include categorisation.rules--# add a third posting for fees, but only if they are non-zero.-if %fees [1-9]- account3 expenses:fees- amount3 %fees--$ hledger -f amazon-orders.csv print-2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed- assets:amazon- expenses:misc $20.00--2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed- assets:amazon- expenses:misc $25.00- expenses:fees $1.00---File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples--11.18.4 Paypal-----------------Here’s a real-world rules file for (customised) Paypal CSV, with some-Paypal-specific rules, and a second rules file included:--"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"-"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""-"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""-"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""-"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""-"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""-"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""-"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""--# paypal-custom.csv.rules--# Tips:-# Export from Activity -> Statements -> Custom -> Activity download-# Suggested transaction type: "Balance affecting"-# Paypal's default fields in 2018 were:-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"-# This rules file assumes the following more detailed fields, configured in "Customize report fields":-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"--fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note--skip 1--date-format %-m/%-d/%Y--# ignore some paypal events-if-In Progress-Temporary Hold-Update to- skip--# add more fields to the description-description %description_ %itemtitle--# save some other fields as tags-comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_--# convert to short currency symbols-if %currency USD- currency $-if %currency EUR- currency E-if %currency GBP- currency P--# generate postings--# the first posting will be the money leaving/entering my paypal account-# (negative means leaving my account, in all amount fields)-account1 assets:online:paypal-amount1 %netamount--# the second posting will be money sent to/received from other party-# (account2 is set below)-amount2 -%grossamount--# if there's a fee, add a third posting for the money taken by paypal.-if %feeamount [1-9]- account3 expenses:banking:paypal- amount3 -%feeamount- comment3 business:--# choose an account for the second posting--# override the default account names:-# if the amount is positive, it's income (a debit)-if %grossamount ^[^-]- account2 income:unknown-# if negative, it's an expense (a credit)-if %grossamount ^-- account2 expenses:unknown--# apply common rules for setting account2 & other tweaks-include common.rules--# apply some overrides specific to this csv--# Transfers from/to bank. These are usually marked Pending,-# which can be disregarded in this case.-if-Bank Account-Bank Deposit to PP Account- description %type for %referencetxnid %itemtitle- account2 assets:bank:wf:pchecking- account1 assets:online:paypal--# Currency conversions-if Currency Conversion- account2 equity:currency conversion--# common.rules--if-darcs-noble benefactor- account2 revenues:foss donations:darcshub- comment2 business:--if-Calm Radio- account2 expenses:online:apps--if-electronic frontier foundation-Patreon-wikimedia-Advent of Code- account2 expenses:dues--if Google- account2 expenses:online:apps- description google | music--$ hledger -f paypal-custom.csv print-2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed- assets:online:paypal $-6.99 = $-6.99- expenses:online:apps $6.99--2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending- assets:online:paypal $6.99 = $0.00- assets:bank:wf:pchecking $-6.99--2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed- assets:online:paypal $-7.00 = $-7.00- expenses:dues $7.00--2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending- assets:online:paypal $7.00 = $0.00- assets:bank:wf:pchecking $-7.00--2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed- assets:online:paypal $-2.00 = $-2.00- expenses:dues $2.00- expenses:banking:paypal ; business:--2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending- assets:online:paypal $2.00 = $0.00- assets:bank:wf:pchecking $-2.00--2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed- assets:online:paypal $9.41 = $9.41- revenues:foss donations:darcshub $-10.00 ; business:- expenses:banking:paypal $0.59 ; business:---File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top--12 Timeclock-************--The time logging format of timeclock.el, as read by hledger.-- hledger can read time logs in timeclock format. As with Ledger,-these are (a subset of) timeclock.el’s format, containing clock-in and-clock-out entries as in the example below. The date is a simple date.-The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are-optional. The timezone, if present, must be four digits and is ignored-(currently the time is always interpreted as a local time). Lines-beginning with ‘#’ or ‘;’ or ‘*’, and blank lines, are ignored.--i 2015/03/30 09:00:00 some:account name optional description after two spaces-o 2015/03/30 09:20:00-i 2015/03/31 22:21:45 another account-o 2015/04/01 02:00:34-- hledger treats each clock-in/clock-out pair as a transaction posting-some number of hours to an account. Or if the session spans more than-one day, it is split into several transactions, one for each day. For-the above time log, ‘hledger print’ generates these journal entries:--$ hledger -f t.timeclock print-2015-03-30 * optional description after two spaces- (some:account name) 0.33h--2015-03-31 * 22:21-23:59- (another account) 1.64h--2015-04-01 * 00:00-02:00- (another account) 2.01h-- Here is a sample.timeclock to download and some queries to try:--$ hledger -f sample.timeclock balance # current time balances-$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009-$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week-- To generate time logs, ie to clock in and clock out, you could:-- • use emacs and the built-in timeclock.el, or the extended- timeclock-x.el and perhaps the extras in ledgerutils.el-- • at the command line, use these bash aliases: ‘shell alias ti="echo- i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o- `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"’-- • or use the old ‘ti’ and ‘to’ scripts in the ledger 2.x repository.- These rely on a "timeclock" executable which I think is just the- ledger 2 executable renamed.---File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top--13 Timedot-**********--‘timedot’ format is hledger’s human-friendly time logging format.-Compared to ‘timeclock’ format, it is-- • convenient for quick, approximate, and retroactive time logging- • readable: you can see at a glance where time was spent.-- A timedot file contains a series of day entries, which might look-like this:--2021-08-04-hom:errands .... ....-fos:hledger:timedot .. ; docs-per:admin:finance -- hledger reads this as three time transactions on this day, with each-dot representing a quarter-hour spent:--$ hledger -f a.timedot print # .timedot file extension activates the timedot reader-2021-08-04 *- (hom:errands) 2.00--2021-08-04 *- (fos:hledger:timedot) 0.50--2021-08-04 *- (per:admin:finance) 0-- A day entry begins with a date line:-- • a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D).-- Optionally this can be followed on the same line by-- • a common *transaction description* for this day- • a common *transaction comment* for this day, after a semicolon- (‘;’).-- After the date line are zero or more optionally-indented time-transaction lines, consisting of:-- • an *account name* - any word or phrase, usually a hledger-style- account name.- • *two or more spaces* - a field separator, required if there is an- amount (as in journal format).- • a *timedot amount* - dots representing quarter hours, or a number- representing hours.- • an optional *comment* beginning with semicolon. This is ignored.-- In more detail, timedot amounts can be:-- • *dots*: zero or more period characters, each representing one- quarter-hour. Spaces are ignored and can be used for grouping.- Eg: ‘.... ..’-- • a *number*, representing hours. Eg: ‘1.5’-- • a *number immediately followed by a unit symbol* ‘s’, ‘m’, ‘h’,- ‘d’, ‘w’, ‘mo’, or ‘y’, representing seconds, minutes, hours, days- weeks, months or years. Eg ‘1.5h’ or ‘90m’. The following- equivalencies are assumed:- ‘60s’ = ‘1m’, ‘60m’ = ‘1h’, ‘24h’ = ‘1d’, ‘7d’ = ‘1w’, ‘30d’ =- ‘1mo’, ‘365d’ = ‘1y’. (This unit will not be visible in the- generated transaction amount, which is always in hours.)-- There is some added flexibility to help with keeping time log data in-the same file as your notes, todo lists, etc.:-- • Blank lines and lines beginning with ‘#’ or ‘;’ are ignored.-- • Before the first date line, lines beginning with ‘*’ are ignored.- From the first date line onward, a sequence of ‘*’’s followed by a- space at beginning of lines (ie, the headline prefix used by Emacs- Org mode) is ignored. This means the time log can be kept under an- Org headline, and date lines or time transaction lines can be Org- headlines.-- • Lines not ending with a double-space and amount are parsed as- transactions with zero amount. (Most hledger reports hide these by- default; add -E to see them.)-- More examples:--# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.-2016/2/1-inc:client1 .... .... .... .... .... ....-fos:haskell .... ..-biz:research .--2016/2/2-inc:client1 .... ....-biz:research .--2016/2/3-inc:client1 4-fos:hledger 3-biz:research 1--* Time log-** 2020-01-01-*** adm:time .-*** adm:finance .--* 2020 Work Diary-** Q1-*** 2020-02-29-**** DONE-0700 yoga-**** UNPLANNED-**** BEGUN-hom:chores- cleaning ...- water plants- outdoor - one full watering can- indoor - light watering-**** TODO-adm:planning: trip-*** LATER-- Reporting:--$ hledger -f a.timedot print date:2016/2/2-2016-02-02 *- (inc:client1) 2.00--2016-02-02 *- (biz:research) 0.25--$ hledger -f a.timedot bal --daily --tree-Balance changes in 2016-02-01-2016-02-03:-- || 2016-02-01d 2016-02-02d 2016-02-03d -============++========================================- biz || 0.25 0.25 1.00 - research || 0.25 0.25 1.00 - fos || 1.50 0 3.00 - haskell || 1.50 0 0 - hledger || 0 0 3.00 - inc || 6.00 2.00 4.00 - client1 || 6.00 2.00 4.00 -------------++----------------------------------------- || 7.75 2.25 8.00 -- Using period instead of colon as account name separator:--2016/2/4-fos.hledger.timedot 4-fos.ledger ..--$ hledger -f a.timedot --alias /\\./=: bal --tree- 4.50 fos- 4.00 hledger:timedot- 0.50 ledger---------------------- 4.50-- A sample.timedot file.---File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top--14 PART 3: REPORTING CONCEPTS-*****************************---File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top--15 Time periods-***************--* Menu:--* Report start & end date::-* Smart dates::-* Report intervals::-* Date adjustment::-* Period expressions::---File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods--15.1 Report start & end date-============================--By default, most hledger reports will show the full span of time-represented by the journal. The report start date will be the earliest-transaction or posting date, and the report end date will be the latest-transaction, posting, or market price date.-- Often you will want to see a shorter time span, such as the current-month. You can specify a start and/or end date using ‘-b/--begin’,-‘-e/--end’, ‘-p/--period’ or a ‘date:’ query (described below). All of-these accept the smart date syntax (below).-- Some notes:-- • End dates are exclusive, as in Ledger, so you should write the date- _after_ the last day you want to see in the report.- • As noted in reporting options: among start/end dates specified with- _options_, the last (i.e. right-most) option takes precedence.- • The effective report start and end dates are the intersection of- the start/end dates from options and that from ‘date:’ queries.- That is, ‘date:2019-01 date:2019 -p'2000 to 2030'’ yields January- 2019, the smallest common time span.- • In some cases a report interval will adjust start/end dates to fall- on interval boundaries (see below).-- Examples:--‘-b begin on St. Patrick’s day 2016-2016/3/17’-‘-e 12/1’ end at the start of december 1st of the current year- (11/30 will be the last date included)-‘-b all transactions on or after the 1st of the current month-thismonth’-‘-p all transactions in the current month-thismonth’-‘date:2016/3/17..’the above written as queries instead (‘..’ can also be- replaced with ‘-’)-‘date:..12/1’-‘date:thismonth..’-‘date:thismonth’---File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods--15.2 Smart dates-================--hledger’s user interfaces accept a "smart date" syntax for added-convenience. Smart dates optionally can be relative to today’s date, be-written with english words, and have less-significant parts omitted-(missing parts are inferred as 1). Some examples:--‘2004/10/1’, exact date, several separators allowed. Year-‘2004-01-01’, is 4+ digits, month is 1-12, day is 1-31-‘2004.9.1’-‘2004’ start of year-‘2004/10’ start of month-‘10/1’ month and day in current year-‘21’ day in current month-‘october, oct’ start of month in current year-‘yesterday, today, -1, 0, 1 days from today-tomorrow’-‘last/this/next -1, 0, 1 periods from the current period-day/week/month/quarter/year’-‘in n n periods from the current period-days/weeks/months/quarters/years’-‘n n periods from the current period-days/weeks/months/quarters/years-ahead’-‘n -n periods from the current period-days/weeks/months/quarters/years-ago’-‘20181201’ 8 digit YYYYMMDD with valid year month and- day-‘201812’ 6 digit YYYYMM with valid year and month-- Some counterexamples - malformed digit sequences might give-surprising results:--‘201813’ 6 digits with an invalid month is parsed as start of- 6-digit year-‘20181301’ 8 digits with an invalid month is parsed as start of- 8-digit year-‘20181232’ 8 digits with an invalid day gives an error-‘201801012’ 9+ digits beginning with a valid YYYYMMDD gives an error-- "Today’s date" can be overridden with the ‘--today’ option, in case-it’s needed for testing or for recreating old reports. (Except for-periodic transaction rules, which are not affected by ‘--today’.)---File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods--15.3 Report intervals-=====================--A report interval can be specified so that reports like register,-balance or activity become multi-period, showing each subperiod as a-separate row or column.-- The following standard intervals can be enabled with command-line-flags:-- • ‘-D/--daily’- • ‘-W/--weekly’- • ‘-M/--monthly’- • ‘-Q/--quarterly’- • ‘-Y/--yearly’-- More complex intervals can be specified using ‘-p/--period’,-described below.---File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods--15.4 Date adjustment-====================--With a report interval (other than daily), report start / end dates-which have not been specified explicitly and in full (eg not ‘-b-2023-01-01’, but ‘-b 2023-01’ or ‘-b 2023’ or unspecified) are-considered flexible:-- • A flexible start date will be automatically adjusted earlier if- needed to fall on a natural interval boundary.- • Similarly, a flexible end date will be adjusted later if needed to- make the last period a whole interval (the same length as the- others).-- This is convenient for producing clean periodic reports (this is-traditional hledger behaviour). By contrast, fully-specified exact-dates will not be adjusted (this is new in hledger 1.29).-- An example: with a journal whose first date is 2023-01-10 and last-date is 2023-03-20:-- • ‘hledger bal -M -b 2023/1/15 -e 2023/3/10’- The report periods will begin on the 15th day of each month,- starting from 2023-01-15, and the last period’s last day will be- 2023-03-09. (Exact start and end dates, neither is adjusted.)-- • ‘hledger bal -M -b 2023-01 -e 2023-04’ or ‘hledger bal -M’- The report periods will begin on the 1st of each month, starting- from 2023-01-01, and the last period’s last day will be 2023-03-31.- (Flexible start and end dates, both are adjusted.)---File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods--15.5 Period expressions-=======================--The ‘-p/--period’ option specifies a period expression, which is a-compact way of expressing a start date, end date, and/or report-interval.-- Here’s a period expression with a start and end date (specifying the-first quarter of 2009):--‘-p "from 2009/1/1 to 2009/4/1"’-- Several keywords like "from" and "to" are supported for readability;-these are optional. "to" can also be written as ".." or "-". The-spaces are also optional, as long as you don’t run two dates together.-So the following are equivalent to the above:--‘-p "2009/1/1 2009/4/1"’-‘-p2009/1/1to2009/4/1’-‘-p2009/1/1..2009/4/1’-- Dates are smart dates, so if the current year is 2009, these are also-equivalent to the above:--‘-p "1/1 4/1"’-‘-p "jan-apr"’-‘-p "this year to 4/1"’-- If you specify only one date, the missing start or end date will be-the earliest or latest transaction date in the journal:--‘-p "from 2009/1/1"’ everything after january 1, 2009-‘-p "since 2009/1"’ the same, since is a synonym-‘-p "from 2009"’ the same-‘-p "to 2009"’ everything before january 1, 2009-- You can also specify a period by writing a single partial or full-date:--‘-p "2009"’ the year 2009; equivalent to “2009/1/1 to 2010/1/1”-‘-p "2009/1"’ the month of january 2009; equivalent to “2009/1/1 to- 2009/2/1”-‘-p the first day of 2009; equivalent to “2009/1/1 to-"2009/1/1"’ 2009/1/2”-- or by using the "Q" quarter-year syntax (case insensitive):--‘-p "2009Q1"’ first quarter of 2009, equivalent to “2009/1/1 to- 2009/4/1”-‘-p "q4"’ fourth quarter of the current year--* Menu:--* Period expressions with a report interval::-* More complex report intervals::-* Multiple weekday intervals::---File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions--15.5.1 Period expressions with a report interval---------------------------------------------------A period expression can also begin with a report interval, separated-from the start/end dates (if any) by a space or the word ‘in’:--‘-p "weekly from 2009/1/1 to 2009/4/1"’-‘-p "monthly in 2008"’-‘-p "quarterly"’---File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions--15.5.2 More complex report intervals---------------------------------------Some more complex intervals can be specified within period expressions,-such as:-- • ‘biweekly’ (every two weeks)- • ‘fortnightly’- • ‘bimonthly’ (every two months)- • ‘every day|week|month|quarter|year’- • ‘every N days|weeks|months|quarters|years’-- Weekly on a custom day:-- • ‘every Nth day of week’ (‘th’, ‘nd’, ‘rd’, or ‘st’ are all accepted- after the number)- • ‘every WEEKDAYNAME’ (full or three-letter english weekday name,- case insensitive)-- Monthly on a custom day:-- • ‘every Nth day [of month]’- • ‘every Nth WEEKDAYNAME [of month]’-- Yearly on a custom day:-- • ‘every MM/DD [of year]’ (month number and day of month number)- • ‘every MONTHNAME DDth [of year]’ (full or three-letter english- month name, case insensitive, and day of month number)- • ‘every DDth MONTHNAME [of year]’ (equivalent to the above)-- Examples:--‘-p "bimonthly from-2008"’-‘-p "every 2 weeks"’-‘-p "every 5 months from-2009/03"’-‘-p "every 2nd day of periods will go from Tue to Tue-week"’-‘-p "every Tue"’ same-‘-p "every 15th day"’ period boundaries will be on 15th of each- month-‘-p "every 2nd Monday"’ period boundaries will be on second Monday- of each month-‘-p "every 11/05"’ yearly periods with boundaries on 5th of- November-‘-p "every 5th November"’ same-‘-p "every Nov 5th"’ same-- Show historical balances at end of the 15th day of each month (N is-an end date, exclusive as always):--$ hledger balance -H -p "every 16th day"-- Group postings from the start of wednesday to end of the following-tuesday (N is both (inclusive) start date and (exclusive) end date):--$ hledger register checking -p "every 3rd day of week"---File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions--15.5.3 Multiple weekday intervals------------------------------------This special form is also supported:-- • ‘every WEEKDAYNAME,WEEKDAYNAME,...’ (full or three-letter english- weekday names, case insensitive)-- Also, ‘weekday’ and ‘weekendday’ are shorthand for-‘mon,tue,wed,thu,fri’ and ‘sat,sun’.-- This is mainly intended for use with ‘--forecast’, to generate-periodic transactions on arbitrary days of the week. It may be less-useful with ‘-p’, since it divides each week into subperiods of unequal-length, which is unusual. (Related: #1632)-- Examples:--‘-p "every dates will be Mon, Wed, Fri; periods will be-mon,wed,fri"’ Mon-Tue, Wed-Thu, Fri-Sun-‘-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will-weekday"’ be Mon, Tue, Wed, Thu, Fri-Sun-‘-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri-weekendday"’---File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top--16 Depth-********--With the ‘--depth NUM’ option (short form: ‘-NUM’), reports will show-accounts only to the specified depth, hiding deeper subaccounts. Use-this when you want a summary with less detail. This flag has the same-effect as a ‘depth:’ query argument: ‘depth:2’, ‘--depth=2’ or ‘-2’ are-equivalent.---File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top--17 Queries-**********--One of hledger’s strengths is being able to quickly report on a precise-subset of your data. Most hledger commands accept optional query-arguments to restrict their scope. The syntax is as follows:-- • Zero or more space-separated query terms. These are most often- account name substrings:-- ‘utilities food:groceries’-- • Terms with spaces or other special characters should be enclosed in- quotes:-- ‘"personal care"’-- • Regular expressions are also supported:-- ‘"^expenses\b" "accounts (payable|receivable)"’-- • Add a query type prefix to match other parts of the data:-- ‘date:202012- desc:amazon cur:USD amt:">100" status:’-- • Add a ‘not:’ prefix to negate a term:-- ‘not:cur:USD’--* Menu:--* Query types::-* Combining query terms::-* Queries and command options::-* Queries and valuation::-* Querying with account aliases::-* Querying with cost or value::---File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries--17.1 Query types-================--Here are the types of query term available. Remember these can also be-prefixed with *‘not:’* to convert them into a negative match.-- *‘acct:REGEX’, ‘REGEX’*-Match account names containing this (case insensitive) regular-expression. This is the default query type when there is no prefix, and-regular expression syntax is typically not needed, so usually we just-write an account name substring, like ‘expenses’ or ‘food’.-- *‘amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N’*-Match postings with a single-commodity amount equal to, less than, or-greater than N. (Postings with multi-commodity amounts are not tested-and will always match.) The comparison has two modes: if N is preceded-by a + or - sign (or is 0), the two signed numbers are compared.-Otherwise, the absolute magnitudes are compared, ignoring sign.-- *‘code:REGEX’*-Match by transaction code (eg check number).-- *‘cur:REGEX’*-Match postings or transactions including any amounts whose-currency/commodity symbol is fully matched by REGEX. (For a partial-match, use ‘.*REGEX.*’). Note, to match special characters which are-regex-significant, you need to escape them with ‘\’. And for characters-which are significant to your shell you may need one more level of-escaping. So eg to match the dollar sign:-‘hledger print cur:\\$’.-- *‘desc:REGEX’*-Match transaction descriptions.-- *‘date:PERIODEXPR’*-Match dates (or with the ‘--date2’ flag, secondary dates) within the-specified period. PERIODEXPR is a period expression with no report-interval. Examples:-‘date:2016’, ‘date:thismonth’, ‘date:2/1-2/15’,-‘date:2021-07-27..nextquarter’.-- *‘date2:PERIODEXPR’*-Match secondary dates within the specified period (independent of the-‘--date2’ flag).-- *‘depth:N’*-Match (or display, depending on command) accounts at or above this-depth.-- *‘note:REGEX’*-Match transaction notes (the part of the description right of ‘|’, or-the whole description if there’s no ‘|’).-- *‘payee:REGEX’*-Match transaction payee/payer names (the part of the description left of-‘|’, or the whole description if there’s no ‘|’).-- *‘real:, real:0’*-Match real or virtual postings respectively.-- *‘status:, status:!, status:*’*-Match unmarked, pending, or cleared transactions respectively.-- *‘type:TYPECODES’*-Match by account type (see Declaring accounts > Account types).-‘TYPECODES’ is one or more of the single-letter account type codes-‘ALERXCV’, case insensitive. Note ‘type:A’ and ‘type:E’ will also match-their respective subtypes ‘C’ (Cash) and ‘V’ (Conversion). Certain-kinds of account alias can disrupt account types, see Rewriting accounts-> Aliases and account types.-- *‘tag:REGEX[=REGEX]’*-Match by tag name, and optionally also by tag value. (To match only by-value, use ‘tag:.=REGEX’.)-- When querying by tag, note that:-- • Accounts also inherit the tags of their parent accounts- • Postings also inherit the tags of their account and their- transaction- • Transactions also acquire the tags of their postings.-- (*‘inacct:ACCTNAME’*-A special query term used automatically in hledger-web only: tells-hledger-web to show the transaction register for an account.)---File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries--17.2 Combining query terms-==========================--When given multiple query terms, most commands select things which-match:-- • any of the description terms AND- • any of the account terms AND- • any of the status terms AND- • all the other terms.-- The print command is a little different, showing transactions which:-- • match any of the description terms AND- • have any postings matching any of the positive account terms AND- • have no postings matching any of the negative account terms AND- • match all the other terms.-- Although these fixed rules are enough for many needs, we do not-support full boolean expressions (#203), (and you should not write AND-or OR in your queries). This makes certain queries hard to express, but-here are some tricks that can help:-- 1. Use a doubled ‘not:’ prefix. Eg, to print only the food expenses- paid with cash:-- $ hledger print food not:not:cash-- 2. Or pre-filter the transactions with ‘print’, piping the result into- a second hledger command (with balance assertions disabled):-- $ hledger print cash | hledger -f- -I balance food---File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries--17.3 Queries and command options-================================--Some queries can also be expressed as command-line options: ‘depth:2’ is-equivalent to ‘--depth 2’, ‘date:2020’ is equivalent to ‘-p 2020’, etc.-When you mix command options and query arguments, generally the-resulting query is their intersection.---File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries--17.4 Queries and valuation-==========================--When amounts are converted to other commodities in cost or value-reports, ‘cur:’ and ‘amt:’ match the old commodity symbol and the old-amount quantity, not the new ones (except in hledger 1.22.0 where it’s-reversed, see #1625).---File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries--17.5 Querying with account aliases-==================================--When account names are rewritten with ‘--alias’ or ‘alias’, note that-‘acct:’ will match either the old or the new account name.---File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries--17.6 Querying with cost or value-================================--When amounts are converted to other commodities in cost or value-reports, note that ‘cur:’ matches the new commodity symbol, and not the-old one, and ‘amt:’ matches the new quantity, and not the old one.-Note: this changed in hledger 1.22, previously it was the reverse, see-the discussion at #1625.---File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top--18 Pivoting-***********--Normally, hledger groups and sums amounts within each account. The-‘--pivot FIELD’ option substitutes some other transaction field for-account names, causing amounts to be grouped and summed by that field’s-value instead. FIELD can be any of the transaction fields ‘status’,-‘code’, ‘description’, ‘payee’, ‘note’, or a tag name. When pivoting on-a tag and a posting has multiple values of that tag, only the first-value is displayed. Values containing ‘colon:separated:parts’ will be-displayed hierarchically, like account names.-- Some examples:--2016/02/16 Yearly Dues Payment- assets:bank account 2 EUR- income:dues -2 EUR ; member: John Doe-- Normal balance report showing account names:--$ hledger balance- 2 EUR assets:bank account- -2 EUR income:dues---------------------- 0-- Pivoted balance report, using member: tag values instead:--$ hledger balance --pivot member- 2 EUR- -2 EUR John Doe---------------------- 0-- One way to show only amounts with a member: value (using a query):--$ hledger balance --pivot member tag:member=.- -2 EUR John Doe---------------------- -2 EUR-- Another way (the acct: query matches against the pivoted "account-name"):--$ hledger balance --pivot member acct:.- -2 EUR John Doe---------------------- -2 EUR---File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top--19 Generating data-******************--Two features for generating transient data (visible only at report time)-are built in to hledger’s journal format:-- • Auto posting rules can generate extra postings on certain- transactions. They are activated by the ‘--auto’ flag.-- • Periodic transaction rules can generate repeating transactions,- usually dated in the future, to help with forecasting or budgeting.- They are activated by the ‘--forecast’ or ‘balance --budget’- options, described next.---File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top--20 Forecasting-**************--The ‘--forecast’ flag activates any periodic transaction rules in the-journal. These will generate temporary additional transactions, usually-recurring and in the future, which will appear in all reports. ‘hledger-print --forecast’ is a good way to see them.-- This can be useful for estimating balances into the future, perhaps-experimenting with different scenarios.-- It could also be useful for scripted data entry: you could describe-recurring transactions, and every so often copy the output of ‘print---forecast’ into the journal.-- The generated transactions will have an extra tag, like-‘generated-transaction:~ PERIODICEXPR’, indicating which periodic rule-generated them. There is also a similar, hidden tag, named-‘_generated-transaction:’, which you can use to reliably match-transactions generated "just now" (rather than ‘print’ed in the past).-- The forecast transactions are generated within a _forecast period_,-which is independent of the report period. (Forecast period sets the-bounds for generated transactions, report period controls which-transactions are reported.) The forecast period begins on:-- • the start date provided within ‘--forecast’’s argument, if any- • otherwise, the later of- • the report start date, if specified (with ‘-b’/‘-p’/‘date:’)- • the day after the latest ordinary transaction in the journal,- if any-- • otherwise today.-- It ends on:-- • the end date provided within ‘--forecast’’s argument, if any- • otherwise, the report end date, if specified (with- ‘-e’/‘-p’/‘date:’)- • otherwise 180 days (6 months) from today.-- Note, this means that ordinary transactions will suppress periodic-transactions, by default; the periodic transactions will not start until-after the last ordinary transaction. This is usually convenient, but-you can get around it in two ways:-- • If you need to record some transactions in the future, make them- periodic transactions (with a single occurrence, eg: ‘~- YYYY-MM-DD’) rather than ordinary transactions. That way they- won’t suppress other periodic transactions.-- • Or give ‘--forecast’ a period expression argument. A forecast- period specified this way can overlap ordinary transactions, and- need not be in the future. Some things to note:-- • You must use ‘=’ between flag and argument; a space won’t- work.- • The period expression can specify the forecast period’s start- date, end date, or both. See also Report start & end date.- • The period expression should not specify a report interval.- (Each periodic transaction rule specifies its own interval.)-- Some examples: ‘--forecast=202001-202004’, ‘--forecast=jan-’,-‘--forecast=2021’.---File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top--21 Budgeting-************--With the balance command’s ‘--budget’ report, each periodic transaction-rule generates recurring budget goals in specified accounts, and goals-and actual performance can be compared. See the balance command’s doc-below.-- See also: Budgeting and Forecasting.---File: hledger.info, Node: Cost reporting, Next: Valuation, Prev: Budgeting, Up: Top--22 Cost reporting-*****************--This section is about recording the cost of things, in transactions-where one commodity is exchanged for another. Eg an exchange of-currency, or a stock purchase or sale. First, a quick glossary:-- • Conversion - an exchange of one currency or commodity for another.- Eg a foreign currency exchange, or a purchase or sale of stock or- cryptocurrency.-- • Conversion transaction - a transaction involving one or more- conversions.-- • Conversion rate - the cost per unit of one commodity in the other,- ie the exchange rate.-- • Cost - how much of one commodity was paid to acquire the other.- And more generally, in hledger docs: the amount exchanged in the- "secondary" commodity (usually your base currency), whether in a- purchase or a sale, and whether expressed per unit or in total.- Also, the "@/@@ PRICE" notation used to represent this.--* Menu:--* -B Convert to cost::-* Equity conversion postings::-* Inferring equity postings from cost::-* Inferring cost from equity postings::-* When to infer cost/equity::-* How to record conversions::-* Cost tips::---File: hledger.info, Node: -B Convert to cost, Next: Equity conversion postings, Up: Cost reporting--22.1 -B: Convert to cost-========================--As discussed in JOURNAL > Costs, when recording a transaction you can-also record the amount’s cost in another commodity, by adding ‘@-UNITPRICE’ or ‘@@ TOTALPRICE’.-- Then you can see a report with amounts converted to cost, by adding-the ‘-B/--cost’ flag. (Mnemonic: "B" from "cost Basis", as in Ledger).-Eg:--2022-01-01- assets:dollars $-135 ; 135 dollars is exchanged for..- assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each--$ hledger bal -N- $-135 assets:dollars- €100 assets:euros-$ hledger bal -N -B- $-135 assets:dollars- $135 assets:euros # <- the euros' cost-- Notes:-- -B is sensitive to the order of postings when a cost is inferred: the-inferred price will be in the commodity of the last amount. So if-example 3’s postings are reversed, while the transaction is equivalent,--B shows something different:--2022-01-01- assets:dollars $-135 ; 135 dollars sold- assets:euros €100 ; for 100 euros--$ hledger bal -N -B- €-100 assets:dollars # <- the dollars' selling price- €100 assets:euros-- The @/@@ cost notation is convenient, but has some drawbacks: it does-not truly balance the transaction, so it disrupts the accounting-equation and tends to causes a non-zero total in balance reports.---File: hledger.info, Node: Equity conversion postings, Next: Inferring equity postings from cost, Prev: -B Convert to cost, Up: Cost reporting--22.2 Equity conversion postings-===============================--By contrast, conventional double entry bookkeeping (DEB) uses a-different notation: an extra pair of equity postings to balance-conversion transactions. In this style, the above entry might be-written:--2022-01-01 one hundred euros purchased at $1.35 each- assets:dollars $-135- equity:conversion $135- equity:conversion €-100- assets:euros €100-- This style is more correct, but it’s also more verbose and makes cost-reporting more difficult for PTA tools.-- Happily, current hledger can read either notation, or convert one to-the other when needed, so you can use the one you prefer.-- You can even use cost notation and equivalent conversion postings at-the same time, for clarity. hledger will ignore the redundancy. But be-sure the cost and conversion posting amounts match, or you’ll see a-not-so-clear transaction balancing error message.---File: hledger.info, Node: Inferring equity postings from cost, Next: Inferring cost from equity postings, Prev: Equity conversion postings, Up: Cost reporting--22.3 Inferring equity postings from cost-========================================--With ‘--infer-equity’, hledger detects transactions written with PTA-cost notation and adds equity conversion postings to them:--2022-01-01- assets:dollars -$135- assets:euros €100 @ $1.35--$ hledger print --infer-equity-2022-01-01- assets:dollars $-135- assets:euros €100 @ $1.35- equity:conversion:$-€:€ €-100 ; generated-posting:- equity:conversion:$-€:$ $135.00 ; generated-posting:-- The conversion account names can be changed with the conversion-account type declaration.-- –infer-equity is useful when when transactions have been recorded-using cost notation, to help preserve the accounting equation and-balance reports’ zero total, or to produce more conventional journal-entries for sharing with non-PTA-users.---File: hledger.info, Node: Inferring cost from equity postings, Next: When to infer cost/equity, Prev: Inferring equity postings from cost, Up: Cost reporting--22.4 Inferring cost from equity postings-========================================--The reverse operation is possible using ‘--infer-costs’, which detects-transactions written with equity conversion postings and adds cost-notation to them:--2022-01-01- assets:dollars $-135- equity:conversion $135- equity:conversion €-100- assets:euros €100--$ hledger print --infer-costs-2022-01-01- assets:dollars $-135 @@ €100- equity:conversion $135- equity:conversion €-100- assets:euros €100-- –infer-costs is useful when combined with -B/–cost, allowing cost-reporting even when transactions have been recorded using equity-postings:--$ hledger print --infer-costs -B-2009-01-01- assets:dollars €-100- assets:euros €100-- Notes:-- For ‘--infer-costs’ to work, an exchange must consist of four-postings:-- 1. two non-equity postings- 2. two equity postings, next to one another- 3. the equity accounts must be declared, with account type- ‘V’/‘Conversion’ (or if they are not declared, they must be named- ‘equity:conversion’, ‘equity:trade’, ‘equity:trading’ or- subaccounts of these)- 4. the equity postings’ amounts must exactly match the non-equity- postings’ amounts.-- Multiple such exchanges can coexist within a single transaction.-- When inferring cost, the order of postings matters: the cost is added-to the first of the non-equity postings involved in the exchange, in the-commodity of the last non-equity posting involved in the exchange. If-you don’t want to write your postings in the required order, you can use-explicit cost notation instead.-- –infer-equity and –infer-costs can be used together, if you have a-mixture of both notations in your journal.---File: hledger.info, Node: When to infer cost/equity, Next: How to record conversions, Prev: Inferring cost from equity postings, Up: Cost reporting--22.5 When to infer cost/equity-==============================--Inferring equity postings or costs is still fairly new, so not enabled-by default. We’re not sure yet if that should change. Here are two-suggestions to try, experience reports welcome:-- 1. When you use -B, always use –infer-costs as well. Eg: ‘hledger bal- -B --infer-costs’-- 2. Always run hledger with both flags enabled. Eg: ‘alias hl="hledger- --infer-equity --infer-costs"’---File: hledger.info, Node: How to record conversions, Next: Cost tips, Prev: When to infer cost/equity, Up: Cost reporting--22.6 How to record conversions-==============================--Essentially there are four ways to record a conversion transaction in-hledger. Here are all of them, with pros and cons.--* Menu:--* Conversion with implicit cost::-* Conversion with explicit cost::-* Conversion with equity postings::-* Conversion with equity postings and explicit cost::---File: hledger.info, Node: Conversion with implicit cost, Next: Conversion with explicit cost, Up: How to record conversions--22.6.1 Conversion with implicit cost---------------------------------------Let’s assume 100 EUR is converted to 120 USD. You can just record the-outflow (100 EUR) and inflow (120 USD) in the appropriate asset account:--2021-01-01- assets:cash -100 EUR- assets:cash 120 USD-- hledger will assume this transaction is balanced, inferring that the-conversion rate must be 1 EUR = 1.20 USD. You can see the inferred rate-by using ‘hledger print -x’.-- Pro:-- • Concise, easy-- Con:-- • Less error checking - typos in amounts or commodity symbols may not- be detected- • Conversion rate is not clear- • Disturbs the accounting equation, unless you add the –infer-equity- flag-- You can prevent accidental implicit conversions due to a mistyped-commodity symbol, by using ‘hledger check commodities’.-- You can prevent implicit conversions entirely, by using ‘hledger-check balancednoautoconversion’, or ‘-s/--strict’.---File: hledger.info, Node: Conversion with explicit cost, Next: Conversion with equity postings, Prev: Conversion with implicit cost, Up: How to record conversions--22.6.2 Conversion with explicit cost---------------------------------------You can add the conversion rate using @ notation:--2021-01-01- assets:cash -100 EUR @ 1.20 USD- assets:cash 120 USD-- Now hledger will check that 100 * 1.20 = 120, and would report an-error otherwise.-- Pro:-- • Still concise- • Makes the conversion rate clear- • Provides more error checking-- Con:-- • Disturbs the accounting equation, unless you add the –infer-equity- flag---File: hledger.info, Node: Conversion with equity postings, Next: Conversion with equity postings and explicit cost, Prev: Conversion with explicit cost, Up: How to record conversions--22.6.3 Conversion with equity postings-----------------------------------------In strict double entry bookkeeping, the above transaction is not-balanced in EUR or in USD, since some EUR disappears, and some USD-appears. This violates the accounting equation (A+L+E=0), and prevents-reports like ‘balancesheetequity’ from showing a zero total.-- The proper way to make it balance is to add a balancing posting for-each commodity, using an equity account:--2021-01-01- assets:cash -100 EUR- equity:conversion 100 EUR- equity:conversion -120 USD- assets:cash 120 USD-- Pro:-- • Preserves the accounting equation- • Keeps track of conversions and related gains/losses in one place- • Standard, works in any double entry accounting system-- Con:-- • More verbose- • Conversion rate is not obvious- • Cost reporting requires adding the –infer-costs flag---File: hledger.info, Node: Conversion with equity postings and explicit cost, Prev: Conversion with equity postings, Up: How to record conversions--22.6.4 Conversion with equity postings and explicit cost-----------------------------------------------------------Here both equity postings and @ notation are used together.--2021-01-01- assets:cash -100 EUR @ 1.20 USD- equity:conversion 100 EUR- equity:conversion -120 USD- assets:cash 120 USD-- Pro:-- • Preserves the accounting equation- • Keeps track of conversions and related gains/losses in one place- • Makes the conversion rate clear- • Provides more error checking-- Con:-- • Most verbose- • Not compatible with ledger---File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cost reporting--22.7 Cost tips-==============-- • Recording the cost/conversion rate explicitly is good because it- makes that clear and helps detect errors.- • Recording equity postings is good because it is correct bookkeeping- and preserves the accounting equation.- • Combining these is possible.- • When you want to see the cost (or sale proceeds) of things, use- ‘-B’ (short form of ‘--cost’).- • If you use conversion postings without cost notation, add- ‘--infer-costs’ also.- • If you use cost notation without conversion postings, and you want- to see a balanced balance sheet or print correct journal entries,- use ‘--infer-equity’.- • Conversion to cost is performed before valuation (described next).---File: hledger.info, Node: Valuation, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top--23 Valuation-************--Instead of reporting amounts in their original commodity, hledger can-convert them to cost/sale amount (using the conversion rate recorded in-the transaction), and/or to market value (using some market price on a-certain date). This is controlled by the ‘--value=TYPE[,COMMODITY]’-option, which will be described below. We also provide the simpler ‘-V’-and ‘-X COMMODITY’ options, and often one of these is all you need:--* Menu:--* -V Value::-* -X Value in specified commodity::-* Valuation date::-* Finding market price::-* --infer-market-prices market prices from transactions::-* Valuation commodity::-* Simple valuation examples::-* --value Flexible valuation::-* More valuation examples::-* Interaction of valuation and queries::-* Effect of valuation on reports::---File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Valuation--23.1 -V: Value-==============--The ‘-V/--market’ flag converts amounts to market value in their default-_valuation commodity_, using the market prices in effect on the-_valuation date(s)_, if any. More on these in a minute.---File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation--23.2 -X: Value in specified commodity-=====================================--The ‘-X/--exchange=COMM’ option is like ‘-V’, except you tell it which-currency you want to convert to, and it tries to convert everything to-that.---File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Valuation--23.3 Valuation date-===================--Since market prices can change from day to day, market value reports-have a valuation date (or more than one), which determines which market-prices will be used.-- For single period reports, if an explicit report end date is-specified, that will be used as the valuation date; otherwise the-valuation date is the journal’s end date.-- For multiperiod reports, each column/period is valued on the last day-of the period, by default.---File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Valuation--23.4 Finding market price-=========================--To convert a commodity A to its market value in another commodity B,-hledger looks for a suitable market price (exchange rate) as follows, in-this order of preference :-- 1. A _declared market price_ or _inferred market price_: A’s latest- market price in B on or before the valuation date as declared by a- P directive, or (with the ‘--infer-market-prices’ flag) inferred- from costs.-- 2. A _reverse market price_: the inverse of a declared or inferred- market price from B to A.-- 3. A _forward chain of market prices_: a synthetic price formed by- combining the shortest chain of "forward" (only 1 above) market- prices, leading from A to B.-- 4. _Any chain of market prices_: a chain of any market prices,- including both forward and reverse prices (1 and 2 above), leading- from A to B.-- There is a limit to the length of these price chains; if hledger-reaches that length without finding a complete chain or exhausting all-possibilities, it will give up (with a "gave up" message visible in-‘--debug=2’ output). That limit is currently 1000.-- Amounts for which no suitable market price can be found, are not-converted.---File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Valuation--23.5 –infer-market-prices: market prices from transactions-==========================================================--Normally, market value in hledger is fully controlled by, and requires,-P directives in your journal. Since adding and updating those can be a-chore, and since transactions usually take place at close to market-value, why not use the recorded costs as additional market prices (as-Ledger does) ? Adding the ‘--infer-market-prices’ flag to ‘-V’, ‘-X’ or-‘--value’ enables this.-- So for example, ‘hledger bs -V --infer-market-prices’ will get market-prices both from P directives and from transactions. If both occur on-the same day, the P directive takes precedence.-- There is a downside: value reports can sometimes be affected in-confusing/undesired ways by your journal entries. If this happens to-you, read all of this Valuation section carefully, and try adding-‘--debug’ or ‘--debug=2’ to troubleshoot.-- ‘--infer-market-prices’ can infer market prices from:-- • multicommodity transactions with explicit prices (‘@’/‘@@’)-- • multicommodity transactions with implicit prices (no ‘@’, two- commodities, unbalanced). (With these, the order of postings- matters. ‘hledger print -x’ can be useful for troubleshooting.)-- • multicommodity transactions with equity postings, if cost is- inferred with ‘--infer-costs’.-- There is a limitation (bug) currently: when a valuation commodity is-not specified, prices inferred with ‘--infer-market-prices’ do not help-select a default valuation commodity, as ‘P’ prices would. So-conversion might not happen because no valuation commodity was detected-(‘--debug=2’ will show this). To be safe, specify the valuation-commmodity, eg:-- • ‘-X EUR --infer-market-prices’, not ‘-V --infer-market-prices’- • ‘--value=then,EUR --infer-market-prices’, not ‘--value=then- --infer-market-prices’-- Signed costs and market prices can be confusing. For reference, here-is the current behaviour, since hledger 1.25. (If you think it should-work differently, see #1870.)--2022-01-01 Positive Unit prices- a A 1- b B -1 @ A 1--2022-01-01 Positive Total prices- a A 1- b B -1 @@ A 1---2022-01-02 Negative unit prices- a A 1- b B 1 @ A -1--2022-01-02 Negative total prices- a A 1- b B 1 @@ A -1---2022-01-03 Double Negative unit prices- a A -1- b B -1 @ A -1--2022-01-03 Double Negative total prices- a A -1- b B -1 @@ A -1-- All of the transactions above are considered balanced (and on each-day, the two transactions are considered equivalent). Here are the-market prices inferred for B:--$ hledger -f- --infer-market-prices prices-P 2022-01-01 B A 1-P 2022-01-01 B A 1.0-P 2022-01-02 B A -1-P 2022-01-02 B A -1.0-P 2022-01-03 B A -1-P 2022-01-03 B A -1.0---File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Valuation--23.6 Valuation commodity-========================--*When you specify a valuation commodity (‘-X COMM’ or ‘--value-TYPE,COMM’):*-hledger will convert all amounts to COMM, wherever it can find a-suitable market price (including by reversing or chaining prices).-- *When you leave the valuation commodity unspecified (‘-V’ or ‘--value-TYPE’):*-For each commodity A, hledger picks a default valuation commodity as-follows, in this order of preference:-- 1. The price commodity from the latest P-declared market price for A- on or before valuation date.-- 2. The price commodity from the latest P-declared market price for A- on any date. (Allows conversion to proceed when there are inferred- prices before the valuation date.)-- 3. If there are no P directives at all (any commodity or date) and the- ‘--infer-market-prices’ flag is used: the price commodity from the- latest transaction-inferred price for A on or before valuation- date.-- This means:-- • If you have P directives, they determine which commodities ‘-V’- will convert, and to what.-- • If you have no P directives, and use the ‘--infer-market-prices’- flag, costs determine it.-- Amounts for which no valuation commodity can be found are not-converted.---File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation--23.7 Simple valuation examples-==============================--Here are some quick examples of ‘-V’:--; one euro is worth this many dollars from nov 1-P 2016/11/01 € $1.10--; purchase some euros on nov 3-2016/11/3- assets:euros €100- assets:checking--; the euro is worth fewer dollars by dec 21-P 2016/12/21 € $1.03-- How many euros do I have ?--$ hledger -f t.j bal -N euros- €100 assets:euros-- What are they worth at end of nov 3 ?--$ hledger -f t.j bal -N euros -V -e 2016/11/4- $110.00 assets:euros-- What are they worth after 2016/12/21 ? (no report end date-specified, defaults to today)--$ hledger -f t.j bal -N euros -V- $103.00 assets:euros---File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation--23.8 –value: Flexible valuation-===============================--‘-V’ and ‘-X’ are special cases of the more general ‘--value’ option:-- --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD.- COMM is an optional commodity symbol.- Shows amounts converted to:- - default valuation commodity (or COMM) using market prices at posting dates- - default valuation commodity (or COMM) using market prices at period end(s)- - default valuation commodity (or COMM) using current market prices- - default valuation commodity (or COMM) using market prices at some date-- The TYPE part selects cost or value and valuation date:--‘--value=then’-- Convert amounts to their value in the default valuation commodity,- using market prices on each posting’s date.-‘--value=end’-- Convert amounts to their value in the default valuation commodity,- using market prices on the last day of the report period (or if- unspecified, the journal’s end date); or in multiperiod reports,- market prices on the last day of each subperiod.-‘--value=now’-- Convert amounts to their value in the default valuation commodity- using current market prices (as of when report is generated).-‘--value=YYYY-MM-DD’-- Convert amounts to their value in the default valuation commodity- using market prices on this date.-- To select a different valuation commodity, add the optional ‘,COMM’-part: a comma, then the target commodity’s symbol. Eg:-*‘--value=now,EUR’*. hledger will do its best to convert amounts to-this commodity, deducing market prices as described above.---File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Valuation--23.9 More valuation examples-============================--Here are some examples showing the effect of ‘--value’, as seen with-‘print’:--P 2000-01-01 A 1 B-P 2000-02-01 A 2 B-P 2000-03-01 A 3 B-P 2000-04-01 A 4 B--2000-01-01- (a) 1 A @ 5 B--2000-02-01- (a) 1 A @ 6 B--2000-03-01- (a) 1 A @ 7 B-- Show the cost of each posting:--$ hledger -f- print --cost-2000-01-01- (a) 5 B--2000-02-01- (a) 6 B--2000-03-01- (a) 7 B-- Show the value as of the last day of the report period (2000-02-29):--$ hledger -f- print --value=end date:2000/01-2000/03-2000-01-01- (a) 2 B--2000-02-01- (a) 2 B-- With no report period specified, that shows the value as of the last-day of the journal (2000-03-01):--$ hledger -f- print --value=end-2000-01-01- (a) 3 B--2000-02-01- (a) 3 B--2000-03-01- (a) 3 B-- Show the current value (the 2000-04-01 price is still in effect-today):--$ hledger -f- print --value=now-2000-01-01- (a) 4 B--2000-02-01- (a) 4 B--2000-03-01- (a) 4 B-- Show the value on 2000/01/15:--$ hledger -f- print --value=2000-01-15-2000-01-01- (a) 1 B--2000-02-01- (a) 1 B--2000-03-01- (a) 1 B-- You may need to explicitly set a commodity’s display style, when-reverse prices are used. Eg this output might be surprising:--P 2000-01-01 A 2B--2000-01-01- a 1B- b--$ hledger print -x -X A-2000-01-01- a 0- b 0-- Explanation: because there’s no amount or commodity directive-specifying a display style for A, 0.5A gets the default style, which-shows no decimal digits. Because the displayed amount looks like zero,-the commodity symbol and minus sign are not displayed either. Adding a-commodity directive sets a more useful display style for A:--P 2000-01-01 A 2B-commodity 0.00A--2000-01-01- a 1B- b--$ hledger print -X A-2000-01-01- a 0.50A- b -0.50A---File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation--23.10 Interaction of valuation and queries-==========================================--When matching postings based on queries in the presence of valuation,-the following happens.-- 1. The query is separated into two parts:- 1. the currency (‘cur:’) or amount (‘amt:’).- 2. all other parts.-- 2. The postings are matched to the currency and amount queries based- on pre-valued amounts.- 3. Valuation is applied to the postings.- 4. The postings are matched to the other parts of the query based on- post-valued amounts.-- See: 1625---File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Valuation--23.11 Effect of valuation on reports-====================================--Here is a reference for how valuation is supposed to affect each part of-hledger’s reports (and a glossary). (It’s wide, you’ll have to scroll-sideways.) It may be useful when troubleshooting. If you find-problems, please report them, ideally with a reproducible example.-Related: #329, #1083.--Report ‘-B’, ‘-V’, ‘-X’ ‘--value=then’ ‘--value=end’‘--value=DATE’,-type ‘--cost’ ‘--value=now’--------------------------------------------------------------------------------*print*-posting cost value at value at posting value at value-amounts report end date report or at- or today journal DATE/today- end-balance unchanged unchanged unchanged unchanged unchanged-assertions/assignments-*register*-starting cost value at valued at day value at value-balance report or each historical report or at-(-H) journal posting was made journal DATE/today- end end-starting cost value at valued at day value at value-balance day before each historical day before at-(-H) report or posting was made report or DATE/today-with journal journal-report start start-interval-posting cost value at value at posting value at value-amounts report or date report or at- journal journal DATE/today- end end-summary summarised value at sum of postings value at value-posting cost period in interval, period at-amounts ends valued at ends DATE/today-with interval start-report-interval-running sum/average sum/average sum/average of sum/average sum/average-total/averageof of displayed values of of- displayed displayed displayed displayed- values values values values-*balance-(bs,-bse, cf,-is)*-balance sums of value at value at posting value at value-changes costs report end date report or at- or today journal DATE/today- of sums of end of of- postings sums of sums- postings of- postings-budget like like like balance like like-amounts balance balance changes balances balance-(–budget) changes changes changes-grand sum of sum of sum of displayed sum of sum of-total displayed displayed valued displayed displayed- values values values values-*balance-(bs,-bse, cf,-is) with-report-interval*-starting sums of value at sums of values value at sums-balances costs of report of postings report of-(-H) postings start of before report start of postings- before sums of start at sums of before- report all respective all report- start postings posting dates postings start- before before- report report- start start-balance sums of same as sums of values balance value-changes costs of –value=end of postings in change in at-(bal, postings period at each DATE/today-is, bs in period respective period, of-–change, posting dates valued at sums-cf period of-–change) ends postings-end sums of same as sums of values period end value-balances costs of –value=end of postings from balances, at-(bal -H, postings before period valued at DATE/today-is –H, from start to period period of-bs, cf) before end at ends sums- report respective of- start to posting dates postings- period end-budget like like like balance like like-amounts balance balance changes/end balances balance-(–budget) changes/end changes/end balances changes/end- balances balances balances-row sums, sums, sums, averages sums, sums,-totals, averages averages of displayed averages averages-row of of values of of-averages displayed displayed displayed displayed-(-T, -A) values values values values-column sums of sums of sums of sums of sums-totals displayed displayed displayed values displayed of- values values values displayed- values-grand sum, sum, sum, average of sum, sum,-total, average of average of column totals average of average-grand column column column of-average totals totals totals column- totals-- ‘--cumulative’ is omitted to save space, it works like ‘-H’ but with-a zero starting balance.-- *Glossary:*--_cost_-- calculated using price(s) recorded in the transaction(s).-_value_-- market value using available market price declarations, or the- unchanged amount if no conversion rate can be found.-_report start_-- the first day of the report period specified with -b or -p or- date:, otherwise today.-_report or journal start_-- the first day of the report period specified with -b or -p or- date:, otherwise the earliest transaction date in the journal,- otherwise today.-_report end_-- the last day of the report period specified with -e or -p or date:,- otherwise today.-_report or journal end_-- the last day of the report period specified with -e or -p or date:,- otherwise the latest transaction date in the journal, otherwise- today.-_report interval_-- a flag (-D/-W/-M/-Q/-Y) or period expression that activates the- report’s multi-period mode (whether showing one or many- subperiods).---File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Valuation, Up: Top--24 PART 4: COMMANDS-*******************--* Menu:--* Commands overview::-* accounts::-* activity::-* add::-* aregister::-* balance::-* balancesheet::-* balancesheetequity::-* cashflow::-* check::-* close::-* codes::-* commodities::-* descriptions::-* diff::-* files::-* help::-* import::-* incomestatement::-* notes::-* payees::-* prices::-* print::-* register::-* rewrite::-* roi::-* stats::-* tags::-* test::---File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS--24.1 Commands overview-======================--Here are the built-in commands:--* Menu:--* DATA ENTRY::-* DATA CREATION::-* DATA MANAGEMENT::-* REPORTS FINANCIAL::-* REPORTS VERSATILE::-* REPORTS BASIC::-* HELP::-* ADD-ONS::---File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview--24.1.1 DATA ENTRY--------------------These data entry commands are the only ones which can modify your-journal file.-- • add - add transactions using terminal prompts- • import - add new transactions from other files, eg CSV files---File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview--24.1.2 DATA CREATION----------------------- • close - generate balance-zeroing/restoring transactions- • rewrite - generate auto postings, like print –auto---File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview--24.1.3 DATA MANAGEMENT------------------------- • check - check for various kinds of error in the data- • diff - compare account transactions in two journal files---File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview--24.1.4 REPORTS, FINANCIAL---------------------------- • aregister (areg) - show transactions in a particular account- • balancesheet (bs) - show assets, liabilities and net worth- • balancesheetequity (bse) - show assets, liabilities and equity- • cashflow (cf) - show changes in liquid assets- • incomestatement (is) - show revenues and expenses---File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview--24.1.5 REPORTS, VERSATILE---------------------------- • balance (bal) - show balance changes, end balances, budgets,- gains..- • print - show transactions or export journal data- • register (reg) - show postings in one or more accounts & running- total- • roi - show return on investments---File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview--24.1.6 REPORTS, BASIC------------------------ • accounts - show account names- • activity - show bar charts of posting counts per period- • codes - show transaction codes- • commodities - show commodity/currency symbols- • descriptions - show transaction descriptions- • files - show input file paths- • notes - show note parts of transaction descriptions- • payees - show payee parts of transaction descriptions- • prices - show market prices- • stats - show journal statistics- • tags - show tag names- • test - run self tests---File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview--24.1.7 HELP-------------- • help - show the hledger manual with info/man/pager---File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview--24.1.8 ADD-ONS-----------------And here are some typical add-on commands. Some of these are installed-by the hledger-install script. If installed, they will appear in-hledger’s commands list:-- • ui - run hledger’s terminal UI- • web - run hledger’s web UI- • iadd - add transactions using a TUI (currently hard to build)- • interest - generate interest transactions- • stockquotes - download market prices from AlphaVantage- • Scripts and add-ons - check-fancyassertions, edit, fifo, git, move,- pijul, plot, and more..-- Next, each command is described in detail, in alphabetical order.---File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS--24.2 accounts-=============--Show account names.-- This command lists account names. By default it shows all known-accounts, either used in transactions or declared with account-directives.-- With query arguments, only matched account names and account names-referenced by matched postings are shown.-- Or it can show just the used accounts (‘--used’/‘-u’), the declared-accounts (‘--declared’/‘-d’), the accounts declared but not used-(‘--unused’), the accounts used but not declared (‘--undeclared’), or-the first account matched by an account name pattern, if any (‘--find’).-- It shows a flat list by default. With ‘--tree’, it uses indentation-to show the account hierarchy. In flat mode you can add ‘--drop N’ to-omit the first few account name components. Account names can be-depth-clipped with ‘depth:N’ or ‘--depth N’ or ‘-N’.-- With ‘--types’, it also shows each account’s type, if it’s known.-(See Declaring accounts > Account types.)-- With ‘--positions’, it also shows the file and line number of each-account’s declaration, if any, and the account’s overall declaration-order; these may be useful when troubleshooting account display order.-- With ‘--directives’, it adds the ‘account’ keyword, showing valid-account directives which can be pasted into a journal file. This is-useful together with ‘--undeclared’ when updating your account-declarations to satisfy ‘hledger check accounts’.-- The ‘--find’ flag can be used to look up a single account name, in-the same way that the ‘aregister’ command does. It returns the-alphanumerically-first matched account name, or if none can be found, it-fails with a non-zero exit code.-- Examples:--$ hledger accounts-assets:bank:checking-assets:bank:saving-assets:cash-expenses:food-expenses:supplies-income:gifts-income:salary-liabilities:debts--$ hledger accounts --undeclared --directives >> $LEDGER_FILE-$ hledger check accounts---File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS--24.3 activity-=============--Show an ascii barchart of posting counts per interval.-- The activity command displays an ascii histogram showing transaction-counts by day, week, month or other reporting interval (by day is the-default). With query arguments, it counts only matched transactions.-- Examples:--$ hledger activity --quarterly-2008-01-01 **-2008-04-01 *******-2008-07-01 -2008-10-01 **---File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: PART 4 COMMANDS--24.4 add-========--Prompt for transactions and add them to the journal. Any arguments will-be used as default inputs for the first N prompts.-- Many hledger users edit their journals directly with a text editor,-or generate them from CSV. For more interactive data entry, there is the-‘add’ command, which prompts interactively on the console for new-transactions, and appends them to the main journal file (which should be-in journal format). Existing transactions are not changed. This is one-of the few hledger commands that writes to the journal file (see also-‘import’).-- To use it, just run ‘hledger add’ and follow the prompts. You can-add as many transactions as you like; when you are finished, enter ‘.’-or press control-d or control-c to exit.-- Features:-- • add tries to provide useful defaults, using the most similar (by- description) recent transaction (filtered by the query, if any) as- a template.- • You can also set the initial defaults with command line arguments.- • Readline-style edit keys can be used during data entry.- • The tab key will auto-complete whenever possible - accounts,- payees/descriptions, dates (‘yesterday’, ‘today’, ‘tomorrow’). If- the input area is empty, it will insert the default value.- • If the journal defines a default commodity, it will be added to any- bare numbers entered.- • A parenthesised transaction code may be entered following a date.- • Comments and tags may be entered following a description or amount.- • If you make a mistake, enter ‘<’ at any prompt to go one step- backward.- • Input prompts are displayed in a different colour when the terminal- supports it.-- Example (see https://hledger.org/add.html for a detailed tutorial):--$ hledger add-Adding transactions to journal file /src/hledger/examples/sample.journal-Any command line arguments will be used as defaults.-Use tab key to complete, readline keys to edit, enter to accept defaults.-An optional (CODE) may follow transaction dates.-An optional ; COMMENT may follow descriptions or amounts.-If you make a mistake, enter < at any prompt to go one step backward.-To end a transaction, enter . when prompted.-To quit, enter . at a date prompt or press control-d or control-c.-Date [2015/05/22]: -Description: supermarket-Account 1: expenses:food-Amount 1: $10-Account 2: assets:checking-Amount 2 [$-10.0]: -Account 3 (or . or enter to finish this transaction): .-2015/05/22 supermarket- expenses:food $10- assets:checking $-10.0--Save this transaction to the journal ? [y]: -Saved.-Starting the next transaction (. or ctrl-D/ctrl-C to quit)-Date [2015/05/22]: <CTRL-D> $-- On Microsoft Windows, the add command makes sure that no part of the-file path ends with a period, as that would cause problems (#1056).---File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS--24.5 aregister-==============--(areg)-- Show the transactions and running historical balance of a single-account, with each transaction displayed as one line.-- ‘aregister’ shows the overall transactions affecting a particular-account (and any subaccounts). Each report line represents one-transaction in this account. Transactions before the report start date-are always included in the running balance (‘--historical’ mode is-always on).-- This is a more "real world", bank-like view than the ‘register’-command (which shows individual postings, possibly from multiple-accounts, not necessarily in historical mode). As a quick rule of-thumb: - use ‘aregister’ for reviewing and reconciling real-world-asset/liability accounts - use ‘register’ for reviewing detailed-revenues/expenses.-- ‘aregister’ requires one argument: the account to report on. You can-write either the full account name, or a case-insensitive regular-expression which will select the alphabetically first matched account.-- When there are multiple matches, the alphabetically-first choice can-be surprising; eg if you have ‘assets:per:checking 1’ and-‘assets:biz:checking 2’ accounts, ‘hledger areg checking’ would select-‘assets:biz:checking 2’. It’s just a convenience to save typing, so if-in doubt, write the full account name, or a distinctive substring that-matches uniquely.-- Transactions involving subaccounts of this account will also be-shown. ‘aregister’ ignores depth limits, so its final total will always-match a balance report with similar arguments.-- Any additional arguments form a query which will filter the-transactions shown. Note some queries will disturb the running balance,-causing it to be different from the account’s real-world running-balance.-- An example: this shows the transactions and historical running-balance during july, in the first account whose name contains-"checking":--$ hledger areg checking date:jul-- Each ‘aregister’ line item shows:-- • the transaction’s date (or the relevant posting’s date if- different, see below)- • the names of all the other account(s) involved in this transaction- (probably abbreviated)- • the total change to this account’s balance from this transaction- • the account’s historical running balance after this transaction.-- Transactions making a net change of zero are not shown by default;-add the ‘-E/--empty’ flag to show them.-- For performance reasons, column widths are chosen based on the first-1000 lines; this means unusually wide values in later lines can cause-visual discontinuities as column widths are adjusted. If you want to-ensure perfect alignment, at the cost of more time and memory, use the-‘--align-all’ flag.-- This command also supports the output destination and output format-options. The output formats supported are ‘txt’, ‘csv’, and ‘json’.--* Menu:--* aregister and custom posting dates::---File: hledger.info, Node: aregister and custom posting dates, Up: aregister--24.5.1 aregister and custom posting dates--------------------------------------------Transactions whose date is outside the report period can still be shown,-if they have a posting to this account dated inside the report period.-(And in this case it’s the posting date that is shown.) This ensures-that ‘aregister’ can show an accurate historical running balance,-matching the one shown by ‘register -H’ with the same arguments.-- To filter strictly by transaction date instead, add the ‘--txn-dates’-flag. If you use this flag and some of your postings have custom dates,-it’s probably best to assume the running balance is wrong.---File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS--24.6 balance-============--(bal)-- Show accounts and their balances.-- ‘balance’ is one of hledger’s oldest and most versatile commands, for-listing account balances, balance changes, values, value changes and-more, during one time period or many. Generally it shows a table, with-rows representing accounts, and columns representing periods.-- Note there are some higher-level variants of the ‘balance’ command-with convenient defaults, which can be simpler to use: ‘balancesheet’,-‘balancesheetequity’, ‘cashflow’ and ‘incomestatement’. When you need-more control, then use ‘balance’.--* Menu:--* balance features::-* Simple balance report::-* Balance report line format::-* Filtered balance report::-* List or tree mode::-* Depth limiting::-* Dropping top-level accounts::-* Showing declared accounts::-* Sorting by amount::-* Percentages::-* Multi-period balance report::-* Balance change end balance::-* Balance report types::-* Budget report::-* Data layout::-* Useful balance reports::---File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance--24.6.1 balance features--------------------------Here’s a quick overview of the ‘balance’ command’s features, followed by-more detailed descriptions and examples. Many of these work with the-higher-level commands as well.-- ‘balance’ can show..-- • accounts as a list (‘-l’) or a tree (‘-t’)- • optionally depth-limited (‘-[1-9]’)- • sorted by declaration order and name, or by amount-- ..and their..-- • balance changes (the default)- • or actual and planned balance changes (‘--budget’)- • or value of balance changes (‘-V’)- • or change of balance values (‘--valuechange’)- • or unrealised capital gain/loss (‘--gain’)-- ..in..-- • one time period (the whole journal period by default)- • or multiple periods (‘-D’, ‘-W’, ‘-M’, ‘-Q’, ‘-Y’, ‘-p INTERVAL’)-- ..either..-- • per period (the default)- • or accumulated since report start date (‘--cumulative’)- • or accumulated since account creation (‘--historical/-H’)-- ..possibly converted to..-- • cost (‘--value=cost[,COMM]’/‘--cost’/‘-B’)- • or market value, as of transaction dates (‘--value=then[,COMM]’)- • or at period ends (‘--value=end[,COMM]’)- • or now (‘--value=now’)- • or at some other date (‘--value=YYYY-MM-DD’)-- ..with..-- • totals (‘-T’), averages (‘-A’), percentages (‘-%’), inverted sign- (‘--invert’)- • rows and columns swapped (‘--transpose’)- • another field used as account name (‘--pivot’)- • custom-formatted line items (single-period reports only)- (‘--format’)- • commodities displayed on the same line or multiple lines- (‘--layout’)-- This command supports the output destination and output format-options, with output formats ‘txt’, ‘csv’, ‘json’, and (multi-period-reports only:) ‘html’. In ‘txt’ output in a colour-supporting terminal,-negative amounts are shown in red.-- The ‘--related’/‘-r’ flag shows the balance of the _other_ postings-in the transactions of the postings which would normally be shown.---File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance--24.6.2 Simple balance report-------------------------------With no arguments, ‘balance’ shows a list of all accounts and their-change of balance - ie, the sum of posting amounts, both inflows and-outflows - during the entire period of the journal. ("Simple" here-means just one column of numbers, covering a single period. You can-also have multi-period reports, described later.)-- For real-world accounts, these numbers will normally be their end-balance at the end of the journal period; more on this below.-- Accounts are sorted by declaration order if any, and then-alphabetically by account name. For instance (using-examples/sample.journal):--$ hledger -f examples/sample.journal bal- $1 assets:bank:saving- $-2 assets:cash- $1 expenses:food- $1 expenses:supplies- $-1 income:gifts- $-1 income:salary- $1 liabilities:debts---------------------- 0 -- Accounts with a zero balance (and no non-zero subaccounts, in tree-mode - see below) are hidden by default. Use ‘-E/--empty’ to show them-(revealing ‘assets:bank:checking’ here):--$ hledger -f examples/sample.journal bal -E- 0 assets:bank:checking- $1 assets:bank:saving- $-2 assets:cash- $1 expenses:food- $1 expenses:supplies- $-1 income:gifts- $-1 income:salary- $1 liabilities:debts---------------------- 0 -- The total of the amounts displayed is shown as the last line, unless-‘-N’/‘--no-total’ is used.---File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance--24.6.3 Balance report line format------------------------------------For single-period balance reports displayed in the terminal (only), you-can use ‘--format FMT’ to customise the format and content of each line.-Eg:--$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"- assets $-1- bank:saving $1- cash $-2- expenses $2- food $1- supplies $1- income $-2- gifts $-1- salary $-1- liabilities:debts $1----------------------------------- 0-- The FMT format string specifies the formatting applied to each-account/balance pair. It may contain any suitable text, with data-fields interpolated like so:-- ‘%[MIN][.MAX](FIELDNAME)’-- • MIN pads with spaces to at least this width (optional)-- • MAX truncates at this width (optional)-- • FIELDNAME must be enclosed in parentheses, and can be one of:-- • ‘depth_spacer’ - a number of spaces equal to the account’s- depth, or if MIN is specified, MIN * depth spaces.- • ‘account’ - the account’s name- • ‘total’ - the account’s balance/posted total, right justified-- Also, FMT can begin with an optional prefix to control how-multi-commodity amounts are rendered:-- • ‘%_’ - render on multiple lines, bottom-aligned (the default)- • ‘%^’ - render on multiple lines, top-aligned- • ‘%,’ - render on one line, comma-separated-- There are some quirks. Eg in one-line mode, ‘%(depth_spacer)’ has no-effect, instead ‘%(account)’ has indentation built in. Experimentation-may be needed to get pleasing results.-- Some example formats:-- • ‘%(total)’ - the account’s total- • ‘%-20.20(account)’ - the account’s name, left justified, padded to- 20 characters and clipped at 20 characters- • ‘%,%-50(account) %25(total)’ - account name padded to 50- characters, total padded to 20 characters, with multiple- commodities rendered on one line- • ‘%20(total) %2(depth_spacer)%-(account)’ - the default format for- the single-column balance report---File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance--24.6.4 Filtered balance report---------------------------------You can show fewer accounts, a different time period, totals from-cleared transactions only, etc. by using query arguments or options to-limit the postings being matched. Eg:--$ hledger -f examples/sample.journal bal --cleared assets date:200806- $-2 assets:cash---------------------- $-2 ---File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance--24.6.5 List or tree mode---------------------------By default, or with ‘-l/--flat’, accounts are shown as a flat list with-their full names visible, as in the examples above.-- With ‘-t/--tree’, the account hierarchy is shown, with subaccounts’-"leaf" names indented below their parent:--$ hledger -f examples/sample.journal balance- $-1 assets- $1 bank:saving- $-2 cash- $2 expenses- $1 food- $1 supplies- $-2 income- $-1 gifts- $-1 salary- $1 liabilities:debts---------------------- 0-- Notes:-- • "Boring" accounts are combined with their subaccount for more- compact output, unless ‘--no-elide’ is used. Boring accounts have- no balance of their own and just one subaccount (eg ‘assets:bank’- and ‘liabilities’ above).-- • All balances shown are "inclusive", ie including the balances from- all subaccounts. Note this means some repetition in the output,- which requires explanation when sharing reports with- non-plaintextaccounting-users. A tree mode report’s final total is- the sum of the top-level balances shown, not of all the balances- shown.-- • Each group of sibling accounts (ie, under a common parent) is- sorted separately.---File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance--24.6.6 Depth limiting------------------------With a ‘depth:NUM’ query, or ‘--depth NUM’ option, or just ‘-NUM’ (eg:-‘-3’) balance reports will show accounts only to the specified depth,-hiding the deeper subaccounts. This can be useful for getting an-overview without too much detail.-- Account balances at the depth limit always include the balances from-any deeper subaccounts (even in list mode). Eg, limiting to depth 1:--$ hledger -f examples/sample.journal balance -1- $-1 assets- $2 expenses- $-2 income- $1 liabilities---------------------- 0 ---File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance--24.6.7 Dropping top-level accounts-------------------------------------You can also hide one or more top-level account name parts, using-‘--drop NUM’. This can be useful for hiding repetitive top-level-account names:--$ hledger -f examples/sample.journal bal expenses --drop 1- $1 food- $1 supplies---------------------- $2 ---File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance--24.6.8 Showing declared accounts-----------------------------------With ‘--declared’, accounts which have been declared with an account-directive will be included in the balance report, even if they have no-transactions. (Since they will have a zero balance, you will also need-‘-E/--empty’ to see them.)-- More precisely, _leaf_ declared accounts (with no subaccounts) will-be included, since those are usually the more useful in reports.-- The idea of this is to be able to see a useful "complete" balance-report, even when you don’t have transactions in all of your declared-accounts yet.---File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance--24.6.9 Sorting by amount---------------------------With ‘-S/--sort-amount’, accounts with the largest (most positive)-balances are shown first. Eg: ‘hledger bal expenses -MAS’ shows your-biggest averaged monthly expenses first. When more than one commodity-is present, they will be sorted by the alphabetically earliest commodity-first, and then by subsequent commodities (if an amount is missing a-commodity, it is treated as 0).-- Revenues and liability balances are typically negative, however, so-‘-S’ shows these in reverse order. To work around this, you can add-‘--invert’ to flip the signs. (Or, use one of the higher-level reports,-which flip the sign automatically. Eg: ‘hledger incomestatement -MAS’).---File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance--24.6.10 Percentages----------------------With ‘-%/--percent’, balance reports show each account’s value expressed-as a percentage of the (column) total.-- Note it is not useful to calculate percentages if the amounts in a-column have mixed signs. In this case, make a separate report for each-sign, eg:--$ hledger bal -% amt:`>0`-$ hledger bal -% amt:`<0`-- Similarly, if the amounts in a column have mixed commodities, convert-them to one commodity with ‘-B’, ‘-V’, ‘-X’ or ‘--value’, or make a-separate report for each commodity:--$ hledger bal -% cur:\\$-$ hledger bal -% cur:€---File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance--24.6.11 Multi-period balance report--------------------------------------With a report interval (set by the ‘-D/--daily’, ‘-W/--weekly’,-‘-M/--monthly’, ‘-Q/--quarterly’, ‘-Y/--yearly’, or ‘-p/--period’ flag),-‘balance’ shows a tabular report, with columns representing successive-time periods (and a title):--$ hledger -f examples/sample.journal bal --quarterly income expenses -E-Balance changes in 2008:-- || 2008q1 2008q2 2008q3 2008q4 -===================++=================================- expenses:food || 0 $1 0 0 - expenses:supplies || 0 $1 0 0 - income:gifts || 0 $-1 0 0 - income:salary || $-1 0 0 0 --------------------++---------------------------------- || $-1 $1 0 0 -- Notes:-- • The report’s start/end dates will be expanded, if necessary, to- fully encompass the displayed subperiods (so that the first and- last subperiods have the same duration as the others).- • Leading and trailing periods (columns) containing all zeroes are- not shown, unless ‘-E/--empty’ is used.- • Accounts (rows) containing all zeroes are not shown, unless- ‘-E/--empty’ is used.- • Amounts with many commodities are shown in abbreviated form, unless- ‘--no-elide’ is used. _(experimental)_- • Average and/or total columns can be added with the ‘-A/--average’- and ‘-T/--row-total’ flags.- • The ‘--transpose’ flag can be used to exchange rows and columns.- • The ‘--pivot FIELD’ option causes a different transaction field to- be used as "account name". See PIVOTING.-- Multi-period reports with many periods can be too wide for easy-viewing in the terminal. Here are some ways to handle that:-- • Hide the totals row with ‘-N/--no-total’- • Convert to a single currency with ‘-V’- • Maximize the terminal window- • Reduce the terminal’s font size- • View with a pager like less, eg: ‘hledger bal -D --color=yes | less- -RS’- • Output as CSV and use a CSV viewer like visidata (‘hledger bal -D- -O csv | vd -f csv’), Emacs’ csv-mode (‘M-x csv-mode, C-c C-a’), or- a spreadsheet (‘hledger bal -D -o a.csv && open a.csv’)- • Output as HTML and view with a browser: ‘hledger bal -D -o a.html- && open a.html’---File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance--24.6.12 Balance change, end balance--------------------------------------It’s important to be clear on the meaning of the numbers shown in-balance reports. Here is some terminology we use:-- A *_balance change_* is the net amount added to, or removed from, an-account during some period.-- An *_end balance_* is the amount accumulated in an account as of some-date (and some time, but hledger doesn’t store that; assume end of day-in your timezone). It is the sum of previous balance changes.-- We call it a *_historical end balance_* if it includes all balance-changes since the account was created. For a real world account, this-means it will match the "historical record", eg the balances reported in-your bank statements or bank web UI. (If they are correct!)-- In general, balance changes are what you want to see when reviewing-revenues and expenses, and historical end balances are what you want to-see when reviewing or reconciling asset, liability and equity accounts.-- ‘balance’ shows balance changes by default. To see accurate-historical end balances:-- 1. Initialise account starting balances with an "opening balances"- transaction (a transfer from equity to the account), unless the- journal covers the account’s full lifetime.-- 2. Include all of of the account’s prior postings in the report, by- not specifying a report start date, or by using the- ‘-H/--historical’ flag. (‘-H’ causes report start date to be- ignored when summing postings.)---File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance--24.6.13 Balance report types-------------------------------The balance command is quite flexible; here is the full detail on how to-control what it reports. If the following seems complicated, don’t-worry - this is for advanced reporting, and it does typically take some-time and experimentation to get clear on all these report modes.-- There are three important option groups:-- ‘hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]-...’--* Menu:--* Calculation type::-* Accumulation type::-* Valuation type::-* Combining balance report types::---File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types--24.6.13.1 Calculation type-..........................--The basic calculation to perform for each table cell. It is one of:-- • ‘--sum’ : sum the posting amounts (*default*)- • ‘--budget’ : sum the amounts, but also show the budget goal amount- (for each account/period)- • ‘--valuechange’ : show the change in period-end historical balance- values (caused by deposits, withdrawals, and/or market price- fluctuations)- • ‘--gain’ : show the unrealised capital gain/loss, (the current- valued balance minus each amount’s original cost)---File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types--24.6.13.2 Accumulation type-...........................--How amounts should accumulate across report periods. Another way to say-it: which time period’s postings should contribute to each cell’s-calculation. It is one of:-- • ‘--change’ : calculate with postings from column start to column- end, ie "just this column". Typically used to see- revenues/expenses. (*default for balance, incomestatement*)-- • ‘--cumulative’ : calculate with postings from report start to- column end, ie "previous columns plus this column". Typically used- to show changes accumulated since the report’s start date. Not- often used.-- • ‘--historical/-H’ : calculate with postings from journal start to- column end, ie "all postings from before report start date until- this column’s end". Typically used to see historical end balances- of assets/liabilities/equity. (*default for balancesheet,- balancesheetequity, cashflow*)---File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types--24.6.13.3 Valuation type-........................--Which kind of value or cost conversion should be applied, if any, before-displaying the report. It is one of:-- • no valuation type : don’t convert to cost or value (*default*)- • ‘--value=cost[,COMM]’ : convert amounts to cost (then optionally to- some other commodity)- • ‘--value=then[,COMM]’ : convert amounts to market value on- transaction dates- • ‘--value=end[,COMM]’ : convert amounts to market value on period- end date(s)- (*default with ‘--valuechange’, ‘--gain’*)- • ‘--value=now[,COMM]’ : convert amounts to market value on today’s- date- • ‘--value=YYYY-MM-DD[,COMM]’ : convert amounts to market value on- another date-- or one of the equivalent simpler flags:-- • ‘-B/--cost’ : like –value=cost (though, note –cost and –value are- independent options which can both be used at once)- • ‘-V/--market’ : like –value=end- • ‘-X COMM/--exchange COMM’ : like –value=end,COMM-- See Cost reporting and Valuation for more about these.---File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types--24.6.13.4 Combining balance report types-........................................--Most combinations of these options should produce reasonable reports,-but if you find any that seem wrong or misleading, let us know. The-following restrictions are applied:-- • ‘--valuechange’ implies ‘--value=end’- • ‘--valuechange’ makes ‘--change’ the default when used with the- ‘balancesheet’/‘balancesheetequity’ commands- • ‘--cumulative’ or ‘--historical’ disables ‘--row-total/-T’-- For reference, here is what the combinations of accumulation and-valuation show:--Valuation:>no valuation ‘--value= then’ ‘--value= end’ ‘--value=-Accumulation:v YYYY-MM-DD- /now’-------------------------------------------------------------------------------‘--change’change in sum of period-end DATE-value- period posting-date value of of change in- market values change in period- in period period-‘--cumulative’change from sum of period-end DATE-value- report start to posting-date value of of change- period end market values change from from report- from report report start start to- start to period to period end period end- end-‘--historicalchange from sum of period-end DATE-value-/-H’ journal start posting-date value of of change- to period end market values change from from journal- (historical end from journal journal start start to- balance) start to period to period end period end- end---File: hledger.info, Node: Budget report, Next: Data layout, Prev: Balance report types, Up: balance--24.6.14 Budget report------------------------The ‘--budget’ report type activates extra columns showing any budget-goals for each account and period. The budget goals are defined by-periodic transactions. This is useful for comparing planned and actual-income, expenses, time usage, etc.-- For example, you can take average monthly expenses in the common-expense categories to construct a minimal monthly budget:--;; Budget-~ monthly- income $2000- expenses:food $400- expenses:bus $50- expenses:movies $30- assets:bank:checking--;; Two months worth of expenses-2017-11-01- income $1950- expenses:food $396- expenses:bus $49- expenses:movies $30- expenses:supplies $20- assets:bank:checking--2017-12-01- income $2100- expenses:food $412- expenses:bus $53- expenses:gifts $100- assets:bank:checking-- You can now see a monthly budget report:--$ hledger balance -M --budget-Budget performance in 2017/11/01-2017/12/31:-- || Nov Dec -======================++====================================================- assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] -----------------------++----------------------------------------------------- || 0 [ 0] 0 [ 0] -- This is different from a normal balance report in several ways:-- • Only accounts with budget goals during the report period are shown,- by default.-- • In each column, in square brackets after the actual amount, budget- goal amounts are shown, and the actual/goal percentage. (Note:- budget goals should be in the same commodity as the actual amount.)-- • All parent accounts are always shown, even in list mode. Eg- assets, assets:bank, and expenses above.-- • Amounts always include all subaccounts, budgeted or unbudgeted,- even in list mode.-- This means that the numbers displayed will not always add up! Eg-above, the ‘expenses’ actual amount includes the gifts and supplies-transactions, but the ‘expenses:gifts’ and ‘expenses:supplies’ accounts-are not shown, as they have no budget amounts declared.-- This can be confusing. When you need to make things clearer, use the-‘-E/--empty’ flag, which will reveal all accounts including unbudgeted-ones, giving the full picture. Eg:--$ hledger balance -M --budget --empty-Budget performance in 2017/11/01-2017/12/31:-- || Nov Dec -======================++====================================================- assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] - expenses || $495 [ 103% of $480] $565 [ 118% of $480] - expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] - expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] - expenses:gifts || 0 $100 - expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] - expenses:supplies || $20 0 - income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] -----------------------++----------------------------------------------------- || 0 [ 0] 0 [ 0] -- You can roll over unspent budgets to next period with ‘--cumulative’:--$ hledger balance -M --budget --cumulative-Budget performance in 2017/11/01-2017/12/31:-- || Nov Dec -======================++====================================================- assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] - expenses || $495 [ 103% of $480] $1060 [ 110% of $960] - expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] - expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] - expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] - income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] -----------------------++----------------------------------------------------- || 0 [ 0] 0 [ 0] -- It’s common to limit budgets/budget reports to just expenses--hledger bal -M --budget expenses-- or just revenues and expenses (eg, using account types):--hledger bal -M --budget type:rx-- It’s also common to limit or convert them to a single currency-(‘cur:COMM’ or ‘-X COMM [--infer-market-prices]’). If showing multiple-currencies, ‘--layout bare’ or ‘--layout tall’ can help.-- For more examples and notes, see Budgeting.--* Menu:--* Budget report start date::-* Budgets and subaccounts::-* Selecting budget goals::-* Budget vs forecast::---File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report--24.6.14.1 Budget report start date-..................................--This might be a bug, but for now: when making budget reports, it’s a-good idea to explicitly set the report’s start date to the first day of-a reporting period, because a periodic rule like ‘~ monthly’ generates-its transactions on the 1st of each month, and if your journal has no-regular transactions on the 1st, the default report start date could-exclude that budget goal, which can be a little surprising. Eg here the-default report period is just the day of 2020-01-15:--~ monthly in 2020- (expenses:food) $500--2020-01-15- expenses:food $400- assets:checking--$ hledger bal expenses --budget-Budget performance in 2020-01-15:-- || 2020-01-15 -==============++============- <unbudgeted> || $400 ---------------++------------- || $400 -- To avoid this, specify the budget report’s period, or at least the-start date, with ‘-b’/‘-e’/‘-p’/‘date:’, to ensure it includes the-budget goal transactions (periodic transactions) that you want. Eg,-adding ‘-b 2020/1/1’ to the above:--$ hledger bal expenses --budget -b 2020/1/1-Budget performance in 2020-01-01..2020-01-15:-- || 2020-01-01..2020-01-15 -===============++========================- expenses:food || $400 [80% of $500] ----------------++------------------------- || $400 [80% of $500] ---File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report--24.6.14.2 Budgets and subaccounts-.................................--You can add budgets to any account in your account hierarchy. If you-have budgets on both parent account and some of its children, then-budget(s) of the child account(s) would be added to the budget of their-parent, much like account balances behave.-- In the most simple case this means that once you add a budget to any-account, all its parents would have budget as well.-- To illustrate this, consider the following budget:--~ monthly from 2019/01- expenses:personal $1,000.00- expenses:personal:electronics $100.00- liabilities-- With this, monthly budget for electronics is defined to be $100 and-budget for personal expenses is an additional $1000, which implicitly-means that budget for both ‘expenses:personal’ and ‘expenses’ is $1100.-- Transactions in ‘expenses:personal:electronics’ will be counted both-towards its $100 budget and $1100 of ‘expenses:personal’ , and-transactions in any other subaccount of ‘expenses:personal’ would be-counted towards only towards the budget of ‘expenses:personal’.-- For example, let’s consider these transactions:--~ monthly from 2019/01- expenses:personal $1,000.00- expenses:personal:electronics $100.00- liabilities--2019/01/01 Google home hub- expenses:personal:electronics $90.00- liabilities $-90.00--2019/01/02 Phone screen protector- expenses:personal:electronics:upgrades $10.00- liabilities--2019/01/02 Weekly train ticket- expenses:personal:train tickets $153.00- liabilities--2019/01/03 Flowers- expenses:personal $30.00- liabilities-- As you can see, we have transactions in-‘expenses:personal:electronics:upgrades’ and ‘expenses:personal:train-tickets’, and since both of these accounts are without explicitly-defined budget, these transactions would be counted towards budgets of-‘expenses:personal:electronics’ and ‘expenses:personal’ accordingly:--$ hledger balance --budget -M-Budget performance in 2019/01:-- || Jan -===============================++===============================- expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - liabilities || $-283.00 [ 26% of $-1100.00] --------------------------------++-------------------------------- || 0 [ 0] -- And with ‘--empty’, we can get a better picture of budget allocation-and consumption:--$ hledger balance --budget -M --empty-Budget performance in 2019/01:-- || Jan -========================================++===============================- expenses || $283.00 [ 26% of $1100.00] - expenses:personal || $283.00 [ 26% of $1100.00] - expenses:personal:electronics || $100.00 [ 100% of $100.00] - expenses:personal:electronics:upgrades || $10.00 - expenses:personal:train tickets || $153.00 - liabilities || $-283.00 [ 26% of $-1100.00] -----------------------------------------++-------------------------------- || 0 [ 0] ---File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report--24.6.14.3 Selecting budget goals-................................--The budget report evaluates periodic transaction rules to generate-special "goal transactions", which generate the goal amounts for each-account in each report subperiod. When troubleshooting, you can use-‘print --forecast’ to show these as forecasted transactions:--$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated-- By default, the budget report uses all available periodic transaction-rules to generate goals. This includes rules with a different report-interval from your report. Eg if you have daily, weekly and monthly-periodic rules, all of these will contribute to the goals in a monthly-budget report.-- You can select a subset of periodic rules by providing an argument to-the ‘--budget’ flag. ‘--budget=DESCPAT’ will match all periodic rules-whose description contains DESCPAT, a case-insensitive substring (not a-regular expression or query). This means you can give your periodic-rules descriptions (remember that two spaces are needed), and then-select from multiple budgets defined in your journal.---File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report--24.6.14.4 Budget vs forecast-............................--‘hledger --forecast ...’ and ‘hledger balance --budget ...’ are separate-features, though both of them use the periodic transaction rules defined-in the journal, and both of them generate temporary transactions for-reporting purposes ("forecast transactions" and "budget goal-transactions", respectively). You can use both features at the same-time if you want. Here are some differences between them, as of hledger-1.29:-- CLI:-- • –forecast is a general hledger option, usable with any command- • –budget is a ‘balance’ command option, usable only with that- command.-- Visibility of generated transactions:-- • forecast transactions are visible in any report, like ordinary- transactions- • budget goal transactions are invisible except for the goal amounts- they produce in –budget reports.-- Periodic transaction rules:-- • –forecast uses all available periodic transaction rules- • –budget uses all periodic rules (‘--budget’) or a selected subset- (‘--budget=DESCPAT’)-- Period of generated transactions:-- • –forecast generates forecast transactions- • from after the last regular transaction to the end of the- report period (‘--forecast’)- • or, during a specified period (‘--forecast=PERIODEXPR’)- • possibly further restricted by a period specified in the- periodic transaction rule- • and always restricted within the bounds of the report period-- • –budget generates budget goal transactions- • throughout the report period- • possibly restricted by a period specified in the periodic- transaction rule.---File: hledger.info, Node: Data layout, Next: Useful balance reports, Prev: Budget report, Up: balance--24.6.15 Data layout----------------------The ‘--layout’ option affects how balance reports show multi-commodity-amounts and commodity symbols, which can improve readability. It can-also normalise the data for easy consumption by other programs. It has-four possible values:-- • ‘--layout=wide[,WIDTH]’: commodities are shown on a single line,- optionally elided to WIDTH- • ‘--layout=tall’: each commodity is shown on a separate line- • ‘--layout=bare’: commodity symbols are in their own column, amounts- are bare numbers- • ‘--layout=tidy’: data is normalised to easily-consumed "tidy" form,- with one row per data value-- Here are the ‘--layout’ modes supported by each output format; note-only CSV output supports all of them:--- txt csv html json sql-----------------------------------------wide Y Y Y-tall Y Y Y-bare Y Y Y-tidy Y-- Examples:-- • Wide layout. With many commodities, reports can be very wide:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide- Balance changes in 2012-01-01..2014-12-31:- - || 2012 2013 2014 Total - ==================++====================================================================================================================================================================================================================- Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT - ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT -- • Limited wide layout. A width limit reduces the width, but some- commodities will be hidden:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32- Balance changes in 2012-01-01..2014-12-31:- - || 2012 2013 2014 Total - ==================++===========================================================================================================================- Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. - ------------------++---------------------------------------------------------------------------------------------------------------------------- || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. -- • Tall layout. Each commodity gets a new line (may be different in- each column), and account names are repeated:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall- Balance changes in 2012-01-01..2014-12-31:- - || 2012 2013 2014 Total - ==================++==================================================- Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - Assets:US:ETrade || 18.00 VHT 294.00 VHT - ------------------++--------------------------------------------------- || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD - || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT - || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD - || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA - || 18.00 VHT 294.00 VHT -- • Bare layout. Commodity symbols are kept in one column, each- commodity gets its own report row, account names are repeated:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare- Balance changes in 2012-01-01..2014-12-31:- - || Commodity 2012 2013 2014 Total - ==================++=============================================- Assets:US:ETrade || GLD 0 70.00 0 70.00 - Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 - Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 - Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 - Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 - ------------------++---------------------------------------------- || GLD 0 70.00 0 70.00 - || ITOT 10.00 18.00 -11.00 17.00 - || USD 337.18 -98.12 4881.44 5120.50 - || VEA 12.00 10.00 14.00 36.00 - || VHT 106.00 18.00 170.00 294.00 -- • Bare layout also affects CSV output, which is useful for producing- data that is easier to consume, eg for making charts:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare- "account","commodity","balance"- "Assets:US:ETrade","GLD","70.00"- "Assets:US:ETrade","ITOT","17.00"- "Assets:US:ETrade","USD","5120.50"- "Assets:US:ETrade","VEA","36.00"- "Assets:US:ETrade","VHT","294.00"- "total","GLD","70.00"- "total","ITOT","17.00"- "total","USD","5120.50"- "total","VEA","36.00"- "total","VHT","294.00"-- • Tidy layout produces normalised "tidy data", where every variable- has its own column and each row represents a single data point.- See- https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html- for more. This is the easiest kind of data for other software to- consume. Here’s how it looks:-- $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy- "account","period","start_date","end_date","commodity","value"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"- "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"- "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"- "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"---File: hledger.info, Node: Useful balance reports, Prev: Data layout, Up: balance--24.6.16 Useful balance reports---------------------------------Some frequently used ‘balance’ options/reports are:-- • ‘bal -M revenues expenses’- Show revenues/expenses in each month. Also available as the- ‘incomestatement’ command.-- • ‘bal -M -H assets liabilities’- Show historical asset/liability balances at each month end. Also- available as the ‘balancesheet’ command.-- • ‘bal -M -H assets liabilities equity’- Show historical asset/liability/equity balances at each month end.- Also available as the ‘balancesheetequity’ command.-- • ‘bal -M assets not:receivable’- Show changes to liquid assets in each month. Also available as the- ‘cashflow’ command.-- Also:-- • ‘bal -M expenses -2 -SA’- Show monthly expenses summarised to depth 2 and sorted by average- amount.-- • ‘bal -M --budget expenses’- Show monthly expenses and budget goals.-- • ‘bal -M --valuechange investments’- Show monthly change in market value of investment assets.-- • ‘bal investments --valuechange -D date:lastweek amt:'>1000' -STA- [--invert]’- Show top gainers [or losers] last week---File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS--24.7 balancesheet-=================--(bs)-- This command displays a balance sheet, showing historical ending-balances of asset and liability accounts. (To see equity as well, use-the balancesheetequity command.) Amounts are shown with normal positive-sign, as in conventional financial statements.-- This report shows accounts declared with the ‘Asset’, ‘Cash’ or-‘Liability’ type (see account types). Or if no such accounts are-declared, it shows top-level accounts named ‘asset’ or ‘liability’ (case-insensitive, plurals allowed) and their subaccounts.-- Example:--$ hledger balancesheet-Balance Sheet--Assets:- $-1 assets- $1 bank:saving- $-2 cash---------------------- $-1--Liabilities:- $1 liabilities:debts---------------------- $1--Total:---------------------- 0-- This command is a higher-level variant of the ‘balance’ command, and-supports many of that command’s features, such as multi-period reports.-It is similar to ‘hledger balance -H assets liabilities’, but with-smarter account detection, and liabilities displayed with their sign-flipped.-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, ‘html’, and-(experimental) ‘json’.---File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS--24.8 balancesheetequity-=======================--(bse)-- This command displays a balance sheet, showing historical ending-balances of asset, liability and equity accounts. Amounts are shown-with normal positive sign, as in conventional financial statements.-- This report shows accounts declared with the ‘Asset’, ‘Cash’,-‘Liability’ or ‘Equity’ type (see account types). Or if no such-accounts are declared, it shows top-level accounts named ‘asset’,-‘liability’ or ‘equity’ (case insensitive, plurals allowed) and their-subaccounts.-- Example:--$ hledger balancesheetequity-Balance Sheet With Equity--Assets:- $-2 assets- $1 bank:saving- $-3 cash---------------------- $-2--Liabilities:- $1 liabilities:debts---------------------- $1--Equity:- $1 equity:owner---------------------- $1--Total:---------------------- 0-- This command is a higher-level variant of the ‘balance’ command, and-supports many of that command’s features, such as multi-period reports.-It is similar to ‘hledger balance -H assets liabilities equity’, but-with smarter account detection, and liabilities/equity displayed with-their sign flipped.-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, ‘html’, and-(experimental) ‘json’.---File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS--24.9 cashflow-=============--(cf)-- This command displays a cashflow statement, showing the inflows and-outflows affecting "cash" (ie, liquid, easily convertible) assets.-Amounts are shown with normal positive sign, as in conventional-financial statements.-- This report shows accounts declared with the ‘Cash’ type (see account-types). Or if no such accounts are declared, it shows accounts-- • under a top-level account named ‘asset’ (case insensitive, plural- allowed)- • whose name contains some variation of ‘cash’, ‘bank’, ‘checking’ or- ‘saving’.-- More precisely: all accounts matching this case insensitive regular-expression:-- ‘^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)’-- and their subaccounts.-- An example cashflow report:--$ hledger cashflow-Cashflow Statement--Cash flows:- $-1 assets- $1 bank:saving- $-2 cash---------------------- $-1--Total:---------------------- $-1-- This command is a higher-level variant of the ‘balance’ command, and-supports many of that command’s features, such as multi-period reports.-It is similar to ‘hledger balance assets not:fixed not:investment-not:receivable’, but with smarter account detection.-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, ‘html’, and-(experimental) ‘json’.---File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS--24.10 check-===========--Check for various kinds of errors in your data.-- hledger provides a number of built-in error checks to help prevent-problems in your data. Some of these are run automatically; or, you can-use this ‘check’ command to run them on demand, with no output and a-zero exit code if all is well. Specify their names (or a prefix) as-argument(s).-- Some examples:--hledger check # basic checks-hledger check -s # basic + strict checks-hledger check ordereddates payees # basic + two other checks-- If you are an Emacs user, you can also configure flycheck-hledger to-run these checks, providing instant feedback as you edit the journal.-- Here are the checks currently available:--* Menu:--* Basic checks::-* Strict checks::-* Other checks::-* Custom checks::-* More about specific checks::---File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check--24.10.1 Basic checks-----------------------These checks are always run automatically, by (almost) all hledger-commands, including ‘check’:-- • *parseable* - data files are well-formed and can be successfully- parsed-- • *balancedwithautoconversion* - all transactions are balanced,- inferring missing amounts where necessary, and possibly converting- commodities using costs or automatically-inferred costs-- • *assertions* - all balance assertions in the journal are passing.- (This check can be disabled with ‘-I’/‘--ignore-assertions’.)---File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check--24.10.2 Strict checks------------------------These additional checks are run when the ‘-s’/‘--strict’ (strict mode)-flag is used. Or, they can be run by giving their names as arguments to-‘check’:-- • *accounts* - all account names used by transactions have been- declared-- • *commodities* - all commodity symbols used have been declared-- • *balancednoautoconversion* - transactions are balanced, possibly- using explicit costs but not inferred ones---File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check--24.10.3 Other checks-----------------------These checks can be run only by giving their names as arguments to-‘check’. They are more specialised and not desirable for everyone,-therefore optional:-- • *ordereddates* - transactions are ordered by date within each file-- • *payees* - all payees used by transactions have been declared-- • *recentassertions* - all accounts with balance assertions have a- balance assertion no more than 7 days before their latest posting-- • *tags* - all tags used by transactions have been declared-- • *uniqueleafnames* - all account leaf names are unique---File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check--24.10.4 Custom checks------------------------A few more checks are are available as separate add-on commands, in-https://github.com/simonmichael/hledger/tree/master/bin:-- • *hledger-check-tagfiles* - all tag values containing / (a forward- slash) exist as file paths-- • *hledger-check-fancyassertions* - more complex balance assertions- are passing-- You could make similar scripts to perform your own custom checks.-See: Cookbook -> Scripting.---File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check--24.10.5 More about specific checks-------------------------------------‘hledger check recentassertions’ will complain if any balance-asserted-account does not have a balance assertion within 7 days before its-latest posting. This aims to prevent the situation where you are-regularly updating your journal, but forgetting to check your balances-against the real world, then one day must dig back through months of-data to find an error. It assumes that adding a balance assertion-requires/reminds you to check the real-world balance. That may not be-true if you auto-generate balance assertions from bank data; in that-case, I recommend to import transactions uncleared, then use the-manual-review-and-mark-cleared phase as a reminder to check the latest-assertions against real-world balances.---File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS--24.11 close-===========--‘close [--retain | --migrate | --open] [QUERY]’-- By default: prints a transaction that zeroes out ("closes") all-accounts, transferring their balances to an equity account. Query-arguments can be added to override the accounts selection. Three other-modes are supported:-- ‘--retain’: prints a transaction closing revenue and expense-balances. This is traditionally done by businesses at the end of each-accounting period; it is less necessary in personal and computer-based-accounting, but it can help balance the accounting equation A=L+E.-- ‘--migrate’: prints a transaction to close asset, liability and most-equity balances, and another transaction to re-open them. This can be-useful when starting a new file (for performance or data protection).-Adding the closing transaction to the old file allows old and new files-to be combined.-- ‘--open’: as above, but prints just the opening transaction. This-can be useful for starting a new file, leaving the old file unchanged.-Similar to Ledger’s equity command.-- You can change the equity account name with ‘--close-acct ACCT’. It-defaults to ‘equity:retained earnings’ with ‘--retain’, or-‘equity:opening/closing balances’ otherwise.-- You can change the transaction description(s) with ‘--close-desc-'DESC'’ and ‘--open-desc 'DESC'’. It defaults to ‘retain earnings’ with-‘--retain’, or ‘closing balances’ and ‘opening balances’ otherwise.-- Just one posting to the equity account will be used by default, with-an implicit amount.-- With ‘--x/--explicit’ the amount will be shown explicitly, and if it-involves multiple commodities, a separate posting will be generated for-each commodity.-- With ‘--interleaved’, each equity posting is shown next to the-corresponding source/destination posting.-- The default closing date is yesterday or the journal’s end date,-whichever is later. You can change this by specifying a report end-date; the last day of the report period will be the closing date. Eg-‘-e 2022’ means "close on 2022-12-31".-- The default closing date is yesterday, or the journal’s end date,-whichever is later. You can change this by specifying a report end-date; (The report start date does not matter.) The last day of the-report period will be the closing date; eg ‘-e 2022’ means "close on-2022-12-31". The opening date is always the day after the closing date.--* Menu:--* close and costs::-* close and balance assertions::-* Example retain earnings::-* Example migrate balances to a new file::-* Example excluding closing/opening transactions::---File: hledger.info, Node: close and costs, Next: close and balance assertions, Up: close--24.11.1 close and costs--------------------------With ‘--show-costs’, any amount costs are shown, with separate postings-for each cost. (This currently the best way to view investment assets,-showing lots and cost bases.) If you have many currency conversion or-investment transactions, it can generate very large journal entries.---File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Prev: close and costs, Up: close--24.11.2 close and balance assertions---------------------------------------Balance assertions will be generated, verifying that the accounts have-been reset to zero (and then restored to their previous balances, if-there is an opening transaction).-- These provide useful error checking, but you can ignore them-temporarily with ‘-I’, or remove them if you prefer.-- You probably should avoid filtering transactions by status or-realness (‘-C’, ‘-R’, ‘status:’), or generating postings (‘--auto’),-with this command, since the balance assertions would depend on these.-- Note custom posting dates spanning the file boundary will disrupt the-balance assertions:--2023-12-30 a purchase made in december, cleared in january- expenses:food 5- assets:bank:checking -5 ; date: 2023-01-02-- To solve that you can transfer the money to and from a temporary-account, in effect splitting the multi-day transaction into two-single-day transactions:--; in 2022.journal:-2022-12-30 a purchase made in december, cleared in january- expenses:food 5- equity:pending -5--; in 2023.journal:-2023-01-02 last year's transaction cleared- equity:pending 5 = 0- assets:bank:checking -5---File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close--24.11.3 Example: retain earnings-----------------------------------Record 2022’s revenues/expenses as retained earnings on 2022-12-31,-appending the generated transaction to the journal:--$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal-- Now 2022’s income statement will show only zeroes. To see it again,-exclude the retain transaction. Eg:--$ hledger -f 2022.journal is not:desc:'retain earnings'---File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close--24.11.4 Example: migrate balances to a new file--------------------------------------------------Close assets/liabilities/equity on 2022-12-31 and re-open them on-2023-01-01:--$ hledger close --migrate -f 2022.journal -p 2022-# copy/paste the closing transaction to the end of 2022.journal-# copy/paste the opening transaction to the start of 2023.journal-- Now 2022’s balance sheet will show only zeroes, indicating a balanced-accounting equation. (Unless you are using @/@@ notation - in that-case, try adding –infer-equity.) To see it again, exclude the closing-transaction. Eg:--$ hledger -f 2022.journal bs not:desc:'closing balances'---File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close--24.11.5 Example: excluding closing/opening transactions----------------------------------------------------------When combining many files for multi-year reports, the closing/opening-transactions cause some noise in reports like ‘print’ and ‘register’.-You can exclude them as shown above, but ‘not:desc:...’ could be-fragile, and also you will need to avoid excluding the very first-opening transaction, which can be awkward. Here is a way to do it,-using tags: add ‘clopen:’ tags to all opening/closing balances-transactions except the first, like this:--; 2021.journal-2021-06-01 first opening balances-...-2021-12-31 closing balances ; clopen:2022-...--; 2022.journal-2022-01-01 opening balances ; clopen:2022-...-2022-12-31 closing balances ; clopen:2023-...--; 2023.journal-2023-01-01 opening balances ; clopen:2023-...-- Now, assuming a combined journal like:--; all.journal-include 2021.journal-include 2022.journal-include 2023.journal-- The ‘clopen:’ tag can exclude all but the first opening transaction.-To show a clean multi-year checking register:--$ hledger -f all.journal areg checking not:tag:clopen-- And the year values allow more precision. To show 2022’s year-end-balance sheet:--$ hledger -f all.journal bs -e2023 not:tag:clopen=2023---File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS--24.12 codes-===========--List the codes seen in transactions, in the order parsed.-- This command prints the value of each transaction’s code field, in-the order transactions were parsed. The transaction code is an optional-value written in parentheses between the date and description, often-used to store a cheque number, order number or similar.-- Transactions aren’t required to have a code, and missing or empty-codes will not be shown by default. With the ‘-E’/‘--empty’ flag, they-will be printed as blank lines.-- You can add a query to select a subset of transactions.-- Examples:--2022/1/1 (123) Supermarket - Food $5.00- Checking --2022/1/2 (124) Post Office- Postage $8.32- Checking--2022/1/3 Supermarket- Food $11.23- Checking --2022/1/4 (126) Post Office- Postage $3.21- Checking--$ hledger codes-123-124-126--$ hledger codes -E-123-124--126---File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: PART 4 COMMANDS--24.13 commodities-=================--List all commodity/currency symbols used or declared in the journal.---File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: PART 4 COMMANDS--24.14 descriptions-==================--List the unique descriptions that appear in transactions.-- This command lists the unique descriptions that appear in-transactions, in alphabetic order. You can add a query to select a-subset of transactions.-- Example:--$ hledger descriptions-Store Name-Gas Station | Petrol-Person A---File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS--24.15 diff-==========--Compares a particular account’s transactions in two input files. It-shows any transactions to this account which are in one file but not in-the other.-- More precisely, for each posting affecting this account in either-file, it looks for a corresponding posting in the other file which posts-the same amount to the same account (ignoring date, description, etc.)-Since postings not transactions are compared, this also works when-multiple bank transactions have been combined into a single journal-entry.-- This is useful eg if you have downloaded an account’s transactions-from your bank (eg as CSV data). When hledger and your bank disagree-about the account balance, you can compare the bank data with your-journal to find out the cause.-- Examples:--$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro -These transactions are in the first file only:--2014/01/01 Opening Balances- assets:bank:giro EUR ...- ...- equity:opening balances EUR -...--These transactions are in the second file only:---File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS--24.16 files-===========--List all files included in the journal. With a REGEX argument, only-file names matching the regular expression (case sensitive) are shown.---File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS--24.17 help-==========--Show the hledger user manual in the terminal, with ‘info’, ‘man’, or a-pager. With a TOPIC argument, open it at that topic if possible. TOPIC-can be any heading in the manual, or a heading prefix, case insensitive.-Eg: ‘commands’, ‘print’, ‘forecast’, ‘journal’, ‘amount’, ‘"auto-postings"’.-- This command shows the hledger manual built in to your hledger-version. It can be useful when offline, or when you prefer the terminal-to a web browser, or when the appropriate hledger manual or viewing-tools are not installed on your system.-- By default it chooses the best viewer found in $PATH (preferring info-since the hledger manual is large). You can select a particular viewer-with the ‘-i’, ‘-m’, or ‘-p’ flags.-- Examples--$ hledger help --help # show how the help command works-$ hledger help # show the hledger manual with info, man or $PAGER-$ hledger help journal # show the journal topic in the hledger manual---File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS--24.18 import-============--Read new transactions added to each FILE since last run, and add them to-the journal. Or with –dry-run, just print the transactions that would-be added. Or with –catchup, just mark all of the FILEs’ transactions as-imported, without actually importing any.-- This command may append new transactions to the main journal file-(which should be in journal format). Existing transactions are not-changed. This is one of the few hledger commands that writes to the-journal file (see also ‘add’).-- Unlike other hledger commands, with ‘import’ the journal file is an-output file, and will be modified, though only by appending (existing-data will not be changed). The input files are specified as arguments,-so to import one or more CSV files to your main journal, you will run-‘hledger import bank.csv’ or perhaps ‘hledger import *.csv’.-- Note you can import from any file format, though CSV files are the-most common import source, and these docs focus on that case.--* Menu:--* Deduplication::-* Import testing::-* Importing balance assignments::-* Commodity display styles::---File: hledger.info, Node: Deduplication, Next: Import testing, Up: import--24.18.1 Deduplication------------------------As a convenience ‘import’ does _deduplication_ while reading-transactions. This does not mean "ignore transactions that look the-same", but rather "ignore transactions that have been seen before".-This is intended for when you are periodically importing foreign data-which may contain already-imported transactions. So eg, if every day-you download bank CSV files containing redundant data, you can safely-run ‘hledger import bank.csv’ and only new transactions will be-imported. (‘import’ is idempotent.)-- Since the items being read (CSV records, eg) often do not come with-unique identifiers, hledger detects new transactions by date, assuming-that:-- 1. new items always have the newest dates- 2. item dates do not change across reads- 3. and items with the same date remain in the same relative order- across reads.-- These are often true of CSV files representing transactions, or true-enough so that it works pretty well in practice. 1 is important, but-violations of 2 and 3 amongst the old transactions won’t matter (and if-you import often, the new transactions will be few, so less likely to be-the ones affected).-- hledger remembers the latest date processed in each input file by-saving a hidden ".latest" state file in the same directory. Eg when-reading ‘finance/bank.csv’, it will look for and update the-‘finance/.latest.bank.csv’ state file. The format is simple: one or-more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I-have processed transactions up to this date, and this many of them on-that date." Normally you won’t see or manipulate these state files-yourself. But if needed, you can delete them to reset the state (making-all transactions "new"), or you can construct them to "catch up" to a-certain date.-- Note deduplication (and updating of state files) can also be done by-‘print --new’, but this is less often used.---File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import--24.18.2 Import testing-------------------------With ‘--dry-run’, the transactions that will be imported are printed to-the terminal, without updating your journal or state files. The output-is valid journal format, like the print command, so you can re-parse it.-Eg, to see any importable transactions which CSV rules have not-categorised:--$ hledger import --dry bank.csv | hledger -f- -I print unknown-- or (live updating):--$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'-- Note: when importing from multiple files at once, it’s currently-possible for some .latest files to be updated successfully, while the-actual import fails because of a problem in one of the files, leaving-them out of sync (and causing some transactions to be missed). To-prevent this, do a –dry-run first and fix any problems before the real-import.---File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import--24.18.3 Importing balance assignments----------------------------------------Entries added by import will have their posting amounts made explicit-(like ‘hledger print -x’). This means that any balance assignments in-imported files must be evaluated; but, imported files don’t get to see-the main file’s account balances. As a result, importing entries with-balance assignments (eg from an institution that provides only balances-and not posting amounts) will probably generate incorrect posting-amounts. To avoid this problem, use print instead of import:--$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE-- (If you think import should leave amounts implicit like print does,-please test it and send a pull request.)---File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import--24.18.4 Commodity display styles-----------------------------------Imported amounts will be formatted according to the canonical commodity-styles (declared or inferred) in the main journal file.---File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS--24.19 incomestatement-=====================--(is)-- This command displays an income statement, showing revenues and-expenses during one or more periods. Amounts are shown with normal-positive sign, as in conventional financial statements.-- This report shows accounts declared with the ‘Revenue’ or ‘Expense’-type (see account types). Or if no such accounts are declared, it shows-top-level accounts named ‘revenue’ or ‘income’ or ‘expense’ (case-insensitive, plurals allowed) and their subaccounts.-- Example:--$ hledger incomestatement-Income Statement--Revenues:- $-2 income- $-1 gifts- $-1 salary---------------------- $-2--Expenses:- $2 expenses- $1 food- $1 supplies---------------------- $2--Total:---------------------- 0-- This command is a higher-level variant of the ‘balance’ command, and-supports many of that command’s features, such as multi-period reports.-It is similar to ‘hledger balance '(revenues|income)' expenses’, but-with smarter account detection, and revenues/income displayed with their-sign flipped.-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, ‘html’, and-(experimental) ‘json’.---File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS--24.20 notes-===========--List the unique notes that appear in transactions.-- This command lists the unique notes that appear in transactions, in-alphabetic order. You can add a query to select a subset of-transactions. The note is the part of the transaction description after-a | character (or if there is no |, the whole description).-- Example:--$ hledger notes-Petrol-Snacks---File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS--24.21 payees-============--List the unique payee/payer names that appear in transactions.-- This command lists unique payee/payer names which have been declared-with payee directives (–declared), used in transaction descriptions-(–used), or both (the default).-- The payee/payer is the part of the transaction description before a |-character (or if there is no |, the whole description).-- You can add query arguments to select a subset of transactions. This-implies –used.-- Example:--$ hledger payees-Store Name-Gas Station-Person A---File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS--24.22 prices-============--Print market price directives from the journal. With-–infer-market-prices, generate additional market prices from costs.-With –infer-reverse-prices, also generate market prices by inverting-known prices. Prices can be filtered by a query. Price amounts are-displayed with their full precision.---File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS--24.23 print-===========--Show transaction journal entries, sorted by date.-- The print command displays full journal entries (transactions) from-the journal file, sorted by date (or with ‘--date2’, by secondary date).-- Amounts are shown mostly normalised to commodity display style, eg-the placement of commodity symbols will be consistent. All of their-decimal places are shown, as in the original journal entry (with one-alteration: in some cases trailing zeroes are added.)-- Amounts are shown right-aligned within each transaction (but not-across all transactions).-- Directives and inter-transaction comments are not shown, currently.-This means the print command is somewhat lossy, and if you are using it-to reformat your journal you should take care to also copy over the-directives and file-level comments.-- Eg:--$ hledger print-2008/01/01 income- assets:bank:checking $1- income:salary $-1--2008/06/01 gift- assets:bank:checking $1- income:gifts $-1--2008/06/02 save- assets:bank:saving $1- assets:bank:checking $-1--2008/06/03 * eat & shop- expenses:food $1- expenses:supplies $1- assets:cash $-2--2008/12/31 * pay off- liabilities:debts $1- assets:bank:checking $-1-- print’s output is usually a valid hledger journal, and you can-process it again with a second hledger command. This can be useful for-certain kinds of search, eg:--# Show running total of food expenses paid from cash.-# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.-$ hledger print assets:cash | hledger -f- -I reg expenses:food-- There are some situations where print’s output can become-unparseable:-- • Valuation affects posting amounts but not balance assertion or- balance assignment amounts, potentially causing those to fail.- • Auto postings can generate postings with too many missing amounts.- • Account aliases can generate bad account names.-- Normally, the journal entry’s explicit or implicit amount style is-preserved. For example, when an amount is omitted in the journal, it-will not appear in the output. Similarly, when a cost is implied but-not written, it will not appear in the output. You can use the-‘-x’/‘--explicit’ flag to make all amounts and costs explicit, which can-be useful for troubleshooting or for making your journal more readable-and robust against data entry errors. ‘-x’ is also implied by using any-of ‘-B’,‘-V’,‘-X’,‘--value’.-- Note, ‘-x’/‘--explicit’ will cause postings with a multi-commodity-amount (these can arise when a multi-commodity transaction has an-implicit amount) to be split into multiple single-commodity postings,-keeping the output parseable.-- With ‘-B’/‘--cost’, amounts with costs are converted to cost using-that price. This can be used for troubleshooting.-- With ‘-m DESC’/‘--match=DESC’, print does a fuzzy search for one-recent transaction whose description is most similar to DESC. DESC-should contain at least two characters. If there is no similar-enough-match, no transaction will be shown and the program exit code will be-non-zero.-- With ‘--new’, hledger prints only transactions it has not seen on a-previous run. This uses the same deduplication system as the ‘import’-command. (See import’s docs for details.)-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, and-(experimental) ‘json’ and ‘sql’.-- Here’s an example of print’s CSV output:--$ hledger print -Ocsv-"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"-"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""-"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""-"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""-"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""-"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""-"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""-"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""-"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""-"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""-"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""-"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""-- • There is one CSV record per posting, with the parent transaction’s- fields repeated.- • The "txnidx" (transaction index) field shows which postings belong- to the same transaction. (This number might change if transactions- are reordered within the file, files are parsed/included in a- different order, etc.)- • The amount is separated into "commodity" (the symbol) and "amount"- (numeric quantity) fields.- • The numeric amount is repeated in either the "credit" or "debit"- column, for convenience. (Those names are not accurate in the- accounting sense; it just puts negative amounts under credit and- zero or greater amounts under debit.)---File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS--24.24 register-==============--(reg)-- Show postings and their running total.-- The register command displays matched postings, across all accounts,-in date order, with their running total or running historical balance.-(See also the ‘aregister’ command, which shows matched transactions in a-specific account.)-- register normally shows line per posting, but note that-multi-commodity amounts will occupy multiple lines (one line per-commodity).-- It is typically used with a query selecting a particular account, to-see that account’s activity:--$ hledger register checking-2008/01/01 income assets:bank:checking $1 $1-2008/06/01 gift assets:bank:checking $1 $2-2008/06/02 save assets:bank:checking $-1 $1-2008/12/31 pay off assets:bank:checking $-1 0-- With ‘--date2’, it shows and sorts by secondary date instead.-- For performance reasons, column widths are chosen based on the first-1000 lines; this means unusually wide values in later lines can cause-visual discontinuities as column widths are adjusted. If you want to-ensure perfect alignment, at the cost of more time and memory, use the-‘--align-all’ flag.-- The ‘--historical’/‘-H’ flag adds the balance from any undisplayed-prior postings to the running total. This is useful when you want to-see only recent activity, with a historically accurate running balance:--$ hledger register checking -b 2008/6 --historical-2008/06/01 gift assets:bank:checking $1 $2-2008/06/02 save assets:bank:checking $-1 $1-2008/12/31 pay off assets:bank:checking $-1 0-- The ‘--depth’ option limits the amount of sub-account detail-displayed.-- The ‘--average’/‘-A’ flag shows the running average posting amount-instead of the running total (so, the final number displayed is the-average for the whole report period). This flag implies ‘--empty’ (see-below). It is affected by ‘--historical’. It works best when showing-just one account and one commodity.-- The ‘--related’/‘-r’ flag shows the _other_ postings in the-transactions of the postings which would normally be shown.-- The ‘--invert’ flag negates all amounts. For example, it can be used-on an income account where amounts are normally displayed as negative-numbers. It’s also useful to show postings on the checking account-together with the related account:--$ hledger register --related --invert assets:checking-- With a reporting interval, register shows summary postings, one per-interval, aggregating the postings to each account:--$ hledger register --monthly income-2008/01 income:salary $-1 $-1-2008/06 income:gifts $-1 $-2-- Periods with no activity, and summary postings with a zero amount,-are not shown by default; use the ‘--empty’/‘-E’ flag to see them:--$ hledger register --monthly income -E-2008/01 income:salary $-1 $-1-2008/02 0 $-1-2008/03 0 $-1-2008/04 0 $-1-2008/05 0 $-1-2008/06 income:gifts $-1 $-2-2008/07 0 $-2-2008/08 0 $-2-2008/09 0 $-2-2008/10 0 $-2-2008/11 0 $-2-2008/12 0 $-2-- Often, you’ll want to see just one line per interval. The ‘--depth’-option helps with this, causing subaccounts to be aggregated:--$ hledger register --monthly assets --depth 1h-2008/01 assets $1 $1-2008/06 assets $-1 0-2008/12 assets $-1 $-1-- Note when using report intervals, if you specify start/end dates-these will be adjusted outward if necessary to contain a whole number of-intervals. This ensures that the first and last intervals are full-length and comparable to the others in the report.-- With ‘-m DESC’/‘--match=DESC’, register does a fuzzy search for one-recent posting whose description is most similar to DESC. DESC should-contain at least two characters. If there is no similar-enough match,-no posting will be shown and the program exit code will be non-zero.--* Menu:--* Custom register output::---File: hledger.info, Node: Custom register output, Up: register--24.24.1 Custom register output---------------------------------register uses the full terminal width by default, except on windows.-You can override this by setting the ‘COLUMNS’ environment variable (not-a bash shell variable) or by using the ‘--width’/‘-w’ option.-- The description and account columns normally share the space equally-(about half of (width - 40) each). You can adjust this by adding a-description width as part of –width’s argument, comma-separated:-‘--width W,D’ . Here’s a diagram (won’t display correctly in –help):--<--------------------------------- width (W) ---------------------------------->-date (10) description (D) account (W-41-D) amount (12) balance (12)-DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA-- and some examples:--$ hledger reg # use terminal width (or 80 on windows)-$ hledger reg -w 100 # use width 100-$ COLUMNS=100 hledger reg # set with one-time environment variable-$ export COLUMNS=100; hledger reg # set till session end (or window resize)-$ hledger reg -w 100,40 # set overall width 100, description width 40-$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40-- This command also supports the output destination and output format-options The output formats supported are ‘txt’, ‘csv’, and-(experimental) ‘json’.---File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS--24.25 rewrite-=============--Print all transactions, rewriting the postings of matched transactions.-For now the only rewrite available is adding new postings, like print-–auto.-- This is a start at a generic rewriter of transaction entries. It-reads the default journal and prints the transactions, like print, but-adds one or more specified postings to any transactions matching QUERY.-The posting amounts can be fixed, or a multiplier of the existing-transaction’s first posting amount.-- Examples:--$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'-$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'-$ hledger-rewrite.hs -f rewrites.hledger-- rewrites.hledger may consist of entries like:--= ^income amt:<0 date:2017- (liabilities:tax) *0.33 ; tax on income- (reserve:grocery) *0.25 ; reserve 25% for grocery- (reserve:) *0.25 ; reserve 25% for grocery-- Note the single quotes to protect the dollar sign from bash, and the-two spaces between account and amount.-- More:--$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...-$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'-$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'-$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'-- Argument for ‘--add-posting’ option is a usual posting of transaction-with an exception for amount specification. More precisely, you can use-‘'*'’ (star symbol) before the amount to indicate that that this is a-factor for an amount of original matched posting. If the amount-includes a commodity name, the new posting amount will be in the new-commodity; otherwise, it will be in the matched posting amount’s-commodity.--* Menu:--* Re-write rules in a file::-* Diff output format::-* rewrite vs print --auto::---File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite--24.25.1 Re-write rules in a file-----------------------------------During the run this tool will execute so called "Automated Transactions"-found in any journal it process. I.e instead of specifying this-operations in command line you can put them in a journal file.--$ rewrite-rules.journal-- Make contents look like this:--= ^income- (liabilities:tax) *.33--= expenses:gifts- budget:gifts *-1- assets:budget *1-- Note that ‘'='’ (equality symbol) that is used instead of date in-transactions you usually write. It indicates the query by which you-want to match the posting to add new ones.--$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal-- This is something similar to the commands pipeline:--$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \- | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \- --add-posting 'assets:budget *1' \- > rewritten-tidy-output.journal-- It is important to understand that relative order of such entries in-journal is important. You can re-use result of previously added-postings.---File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite--24.25.2 Diff output format-----------------------------To use this tool for batch modification of your journal files you may-find useful output in form of unified diff.--$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'-- Output might look like:----- /tmp/examples/sample.journal-+++ /tmp/examples/sample.journal-@@ -18,3 +18,4 @@- 2008/01/01 income-- assets:bank:checking $1-+ assets:bank:checking $1- income:salary-+ (liabilities:tax) 0-@@ -22,3 +23,4 @@- 2008/06/01 gift-- assets:bank:checking $1-+ assets:bank:checking $1- income:gifts-+ (liabilities:tax) 0-- If you’ll pass this through ‘patch’ tool you’ll get transactions-containing the posting that matches your query be updated. Note that-multiple files might be update according to list of input files-specified via ‘--file’ options and ‘include’ directives inside of these-files.-- Be careful. Whole transaction being re-formatted in a style of-output from ‘hledger print’.-- See also:-- https://github.com/simonmichael/hledger/issues/99---File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite--24.25.3 rewrite vs. print –auto----------------------------------This command predates print –auto, and currently does much the same-thing, but with these differences:-- • with multiple files, rewrite lets rules in any file affect all- other files. print –auto uses standard directive scoping; rules- affect only child files.-- • rewrite’s query limits which transactions can be rewritten; all are- printed. print –auto’s query limits which transactions are- printed.-- • rewrite applies rules specified on command line or in the journal.- print –auto applies rules specified in the journal.---File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: PART 4 COMMANDS--24.26 roi-=========--Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on-your investments.-- At a minimum, you need to supply a query (which could be just an-account name) to select your investment(s) with ‘--inv’, and another-query to identify your profit and loss transactions with ‘--pnl’.-- If you do not record changes in the value of your investment-manually, or do not require computation of time-weighted return (TWR),-‘--pnl’ could be an empty query (‘--pnl ""’ or ‘--pnl STR’ where ‘STR’-does not match any of your accounts).-- This command will compute and display the internalized rate of return-(IRR) and time-weighted rate of return (TWR) for your investments for-the time period requested. Both rates of return are annualized before-display, regardless of the length of reporting interval.-- Price directives will be taken into account if you supply appropriate-‘--cost’ or ‘--value’ flags (see VALUATION).-- Note, in some cases this report can fail, for these reasons:-- • Error (NotBracketed): No solution for Internal Rate of Return- (IRR). Possible causes: IRR is huge (>1000000%), balance of- investment becomes negative at some point in time.- • Error (SearchFailed): Failed to find solution for Internal Rate of- Return (IRR). Either search does not converge to a solution, or- converges too slowly.-- Examples:-- • Using roi to compute total return of investment in stocks:- https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger-- • Cookbook > Return on Investment: https://hledger.org/roi.html--* Menu:--* Spaces and special characters in --inv and --pnl::-* Semantics of --inv and --pnl::-* IRR and TWR explained::---File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi--24.26.1 Spaces and special characters in ‘--inv’ and-------------------------------------------------------‘--pnl’ Note that ‘--inv’ and ‘--pnl’’s argument is a query, and queries-could have several space-separated terms (see QUERIES).-- To indicate that all search terms form single command-line argument,-you will need to put them in quotes (see Special characters):--$ hledger roi --inv 'term1 term2 term3 ...'-- If any query terms contain spaces themselves, you will need an extra-level of nested quoting, eg:--$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"---File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi--24.26.2 Semantics of ‘--inv’ and ‘--pnl’-------------------------------------------Query supplied to ‘--inv’ has to match all transactions that are related-to your investment. Transactions not matching ‘--inv’ will be ignored.-- In these transactions, ROI will conside postings that match ‘--inv’-to be "investment postings" and other postings (not matching ‘--inv’)-will be sorted into two categories: "cash flow" and "profit and loss",-as ROI needs to know which part of the investment value is your-contributions and which is due to the return on investment.-- • "Cash flow" is depositing or withdrawing money, buying or selling- assets, or otherwise converting between your investment commodity- and any other commodity. Example:-- 2019-01-01 Investing in Snake Oil- assets:cash -$100- investment:snake oil- - 2020-01-01 Selling my Snake Oil- assets:cash $10- investment:snake oil = 0-- • "Profit and loss" is change in the value of your investment:-- 2019-06-01 Snake Oil falls in value- investment:snake oil = $57- equity:unrealized profit or loss-- All non-investment postings are assumed to be "cash flow", unless-they match ‘--pnl’ query. Changes in value of your investment due to-"profit and loss" postings will be considered as part of your investment-return.-- Example: if you use ‘--inv snake --pnl equity:unrealized’, then-postings in the example below would be classifed as:--2019-01-01 Snake Oil #1- assets:cash -$100 ; cash flow posting- investment:snake oil ; investment posting--2019-03-01 Snake Oil #2- equity:unrealized pnl -$100 ; profit and loss posting- snake oil ; investment posting--2019-07-01 Snake Oil #3- equity:unrealized pnl ; profit and loss posting- cash -$100 ; cash flow posting- snake oil $50 ; investment posting---File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi--24.26.3 IRR and TWR explained--------------------------------"ROI" stands for "return on investment". Traditionally this was-computed as a difference between current value of investment and its-initial value, expressed in percentage of the initial value.-- However, this approach is only practical in simple cases, where-investments receives no in-flows or out-flows of money, and where rate-of growth is fixed over time. For more complex scenarios you need-different ways to compute rate of return, and this command implements-two of them: IRR and TWR.-- Internal rate of return, or "IRR" (also called "money-weighted rate-of return") takes into account effects of in-flows and out-flows.-Naively, if you are withdrawing from your investment, your future gains-would be smaller (in absolute numbers), and will be a smaller percentage-of your initial investment, and if you are adding to your investment,-you will receive bigger absolute gains (but probably at the same rate of-return). IRR is a way to compute rate of return for each period between-in-flow or out-flow of money, and then combine them in a way that gives-you a compound annual rate of return that investment is expected to-generate.-- As mentioned before, in-flows and out-flows would be any cash that-you personally put in or withdraw, and for the "roi" command, these are-the postings that match the query in the‘--inv’ argument and NOT match-the query in the‘--pnl’ argument.-- If you manually record changes in the value of your investment as-transactions that balance them against "profit and loss" (or "unrealized-gains") account or use price directives, then in order for IRR to-compute the precise effect of your in-flows and out-flows on the rate of-return, you will need to record the value of your investement on or-close to the days when in- or out-flows occur.-- In technical terms, IRR uses the same approach as computation of net-present value, and tries to find a discount rate that makes net present-value of all the cash flows of your investment to add up to zero. This-could be hard to wrap your head around, especially if you haven’t done-discounted cash flow analysis before. Implementation of IRR in hledger-should produce results that match the ‘XIRR’ formula in Excel.-- Second way to compute rate of return that ‘roi’ command implements is-called "time-weighted rate of return" or "TWR". Like IRR, it will also-break the history of your investment into periods between in-flows,-out-flows and value changes, to compute rate of return per each period-and then a compound rate of return. However, internal workings of TWR-are quite different.-- TWR represents your investment as an imaginary "unit fund" where-in-flows/ out-flows lead to buying or selling "units" of your investment-and changes in its value change the value of "investment unit". Change-in "unit price" over the reporting period gives you rate of return of-your investment.-- References:-- • Explanation of rate of return- • Explanation of IRR- • Explanation of TWR- • Examples of computing IRR and TWR and discussion of the limitations- of both metrics---File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS--24.27 stats-===========--Show journal and performance statistics.-- The stats command displays summary information for the whole journal,-or a matched part of it. With a reporting interval, it shows a report-for each report period.-- At the end, it shows (in the terminal) the overall run time and-number of transactions processed per second. Note these are approximate-and will vary based on machine, current load, data size, hledger-version, haskell lib versions, GHC version.. but they may be of-interest. The ‘stats’ command’s run time is similar to that of a-single-column balance report.-- Example:--$ hledger stats -f examples/1000x1000x10.journal-Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal-Included files : -Transactions span : 2000-01-01 to 2002-09-27 (1000 days)-Last transaction : 2002-09-26 (6995 days ago)-Transactions : 1000 (1.0 per day)-Transactions last 30 days: 0 (0.0 per day)-Transactions last 7 days : 0 (0.0 per day)-Payees/descriptions : 1000-Accounts : 1000 (depth 10)-Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)-Market prices : 1000 (A)--Run time : 0.12 s-Throughput : 8342 txns/s-- This command supports the -o/–output-file option (but not--O/–output-format selection).---File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS--24.28 tags-==========--List the tags used in the journal, or their values.-- This command lists the tag names used in the journal, whether on-transactions, postings, or account declarations.-- With a TAGREGEX argument, only tag names matching this regular-expression (case insensitive, infix matched) are shown.-- With QUERY arguments, only transactions and accounts matching this-query are considered. If the query involves transaction fields (date:,-desc:, amt:, ...), the search is restricted to the matched transactions-and their accounts.-- With the –values flag, the tags’ unique non-empty values are listed-instead. With -E/–empty, blank/empty values are also shown.-- With –parsed, tags or values are shown in the order they were parsed,-with duplicates included. (Except, tags from account declarations are-always shown first.)-- Tip: remember, accounts also acquire tags from their parents,-postings also acquire tags from their account and transaction,-transactions also acquire tags from their postings.---File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS--24.29 test-==========--Run built-in unit tests.-- This command runs the unit tests built in to hledger and hledger-lib,-printing the results on stdout. If any test fails, the exit code will-be non-zero.-- This is mainly used by hledger developers, but you can also use it to-sanity-check the installed hledger executable on your platform. All-tests are expected to pass - if you ever see a failure, please report as-a bug!-- This command also accepts tasty test runner options, written after a-– (double hyphen). Eg to run only the tests in Hledger.Data.Amount,-with ANSI colour codes disabled:--$ hledger test -- -pData.Amount --color=never-- For help on these, see https://github.com/feuerbach/tasty#options-(‘-- --help’ currently doesn’t show them).---File: hledger.info, Node: PART 5 COMMON TASKS, Prev: PART 4 COMMANDS, Up: Top--25 PART 5: COMMON TASKS-***********************--Here are some quick examples of how to do some basic tasks with hledger.--* Menu:--* Getting help::-* Constructing command lines::-* Starting a journal file::-* Setting opening balances::-* Recording transactions::-* Reconciling::-* Reporting::-* Migrating to a new file::---File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS--25.1 Getting help-=================--Here’s how to list commands and view options and command docs:--$ hledger # show available commands-$ hledger --help # show common options-$ hledger CMD --help # show CMD's options, common options and CMD's documentation-- You can also view your hledger version’s manual in several formats by-using the help command. Eg:--$ hledger help # show the hledger manual with info, man or $PAGER (best available)-$ hledger help journal # show the journal topic in the hledger manual-$ hledger help --help # find out more about the help command-- To view manuals and introductory docs on the web, visit-https://hledger.org. Chat and mail list support and discussion archives-can be found at https://hledger.org/support.---File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS--25.2 Constructing command lines-===============================--hledger has a flexible command line interface. We strive to keep it-simple and ergonomic, but if you run into one of the sharp edges-described in OPTIONS, here are some tips that might help:-- • command-specific options must go after the command (it’s fine to- put common options there too: ‘hledger CMD OPTS ARGS’)- • running add-on executables directly simplifies command line parsing- (‘hledger-ui OPTS ARGS’)- • enclose "problematic" args in single quotes- • if needed, also add a backslash to hide regular expression- metacharacters from the shell- • to see how a misbehaving command line is being parsed, add- ‘--debug=2’.---File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: PART 5 COMMON TASKS--25.3 Starting a journal file-============================--hledger looks for your accounting data in a journal file,-‘$HOME/.hledger.journal’ by default:--$ hledger stats-The hledger journal file "/Users/simon/.hledger.journal" was not found.-Please create it first, eg with "hledger add" or a text editor.-Or, specify an existing journal file with -f or LEDGER_FILE.-- You can override this by setting the ‘LEDGER_FILE’ environment-variable. It’s a good practice to keep this important file under-version control, and to start a new file each year. So you could do-something like this:--$ mkdir ~/finance-$ cd ~/finance-$ git init-Initialized empty Git repository in /Users/simon/finance/.git/-$ touch 2020.journal-$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc-$ source ~/.bashrc-$ hledger stats-Main file : /Users/simon/finance/2020.journal-Included files : -Transactions span : to (0 days)-Last transaction : none-Transactions : 0 (0.0 per day)-Transactions last 30 days: 0 (0.0 per day)-Transactions last 7 days : 0 (0.0 per day)-Payees/descriptions : 0-Accounts : 0 (depth 0)-Commodities : 0 ()-Market prices : 0 ()---File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: PART 5 COMMON TASKS--25.4 Setting opening balances-=============================--Pick a starting date for which you can look up the balances of some-real-world assets (bank accounts, wallet..) and liabilities (credit-cards..).-- To avoid a lot of data entry, you may want to start with just one or-two accounts, like your checking account or cash wallet; and pick a-recent starting date, like today or the start of the week. You can-always come back later and add more accounts and older transactions, eg-going back to january 1st.-- Add an opening balances transaction to the journal, declaring the-balances on this date. Here are two ways to do it:-- • The first way: open the journal in any text editor and save an- entry like this:-- 2020-01-01 * opening balances- assets:bank:checking $1000 = $1000- assets:bank:savings $2000 = $2000- assets:cash $100 = $100- liabilities:creditcard $-50 = $-50- equity:opening/closing balances-- These are start-of-day balances, ie whatever was in the account at- the end of the previous day.-- The * after the date is an optional status flag. Here it means- "cleared & confirmed".-- The currency symbols are optional, but usually a good idea as- you’ll be dealing with multiple currencies sooner or later.-- The = amounts are optional balance assertions, providing extra- error checking.-- • The second way: run ‘hledger add’ and follow the prompts to record- a similar transaction:-- $ hledger add- Adding transactions to journal file /Users/simon/finance/2020.journal- Any command line arguments will be used as defaults.- Use tab key to complete, readline keys to edit, enter to accept defaults.- An optional (CODE) may follow transaction dates.- An optional ; COMMENT may follow descriptions or amounts.- If you make a mistake, enter < at any prompt to go one step backward.- To end a transaction, enter . when prompted.- To quit, enter . at a date prompt or press control-d or control-c.- Date [2020-02-07]: 2020-01-01- Description: * opening balances- Account 1: assets:bank:checking- Amount 1: $1000- Account 2: assets:bank:savings- Amount 2 [$-1000]: $2000- Account 3: assets:cash- Amount 3 [$-3000]: $100- Account 4: liabilities:creditcard- Amount 4 [$-3100]: $-50- Account 5: equity:opening/closing balances- Amount 5 [$-3050]: - Account 6 (or . or enter to finish this transaction): .- 2020-01-01 * opening balances- assets:bank:checking $1000- assets:bank:savings $2000- assets:cash $100- liabilities:creditcard $-50- equity:opening/closing balances $-3050- - Save this transaction to the journal ? [y]: - Saved.- Starting the next transaction (. or ctrl-D/ctrl-C to quit)- Date [2020-01-01]: .-- If you’re using version control, this could be a good time to commit-the journal. Eg:--$ git commit -m 'initial balances' 2020.journal---File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS--25.5 Recording transactions-===========================--As you spend or receive money, you can record these transactions using-one of the methods above (text editor, hledger add) or by using the-hledger-iadd or hledger-web add-ons, or by using the import command to-convert CSV data downloaded from your bank.-- Here are some simple transactions, see the hledger_journal(5) manual-and hledger.org for more ideas:--2020/1/10 * gift received- assets:cash $20- income:gifts--2020.1.12 * farmers market- expenses:food $13- assets:cash--2020-01-15 paycheck- income:salary- assets:bank:checking $1000---File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS--25.6 Reconciling-================--Periodically you should reconcile - compare your hledger-reported-balances against external sources of truth, like bank statements or your-bank’s website - to be sure that your ledger accurately represents the-real-world balances (and, that the real-world institutions have not made-a mistake!). This gets easy and fast with (1) practice and (2)-frequency. If you do it daily, it can take 2-10 minutes. If you let it-pile up, expect it to take longer as you hunt down errors and-discrepancies.-- A typical workflow:-- 1. Reconcile cash. Count what’s in your wallet. Compare with what- hledger reports (‘hledger bal cash’). If they are different, try- to remember the missing transaction, or look for the error in the- already-recorded transactions. A register report can be helpful- (‘hledger reg cash’). If you can’t find the error, add an- adjustment transaction. Eg if you have $105 after the above, and- can’t explain the missing $2, it could be:-- 2020-01-16 * adjust cash- assets:cash $-2 = $105- expenses:misc-- 2. Reconcile checking. Log in to your bank’s website. Compare- today’s (cleared) balance with hledger’s cleared balance (‘hledger- bal checking -C’). If they are different, track down the error or- record the missing transaction(s) or add an adjustment transaction,- similar to the above. Unlike the cash case, you can usually- compare the transaction history and running balance from your bank- with the one reported by ‘hledger reg checking -C’. This will be- easier if you generally record transaction dates quite similar to- your bank’s clearing dates.-- 3. Repeat for other asset/liability accounts.-- Tip: instead of the register command, use hledger-ui to see a-live-updating register while you edit the journal: ‘hledger-ui --watch---register checking -C’-- After reconciling, it could be a good time to mark the reconciled-transactions’ status as "cleared and confirmed", if you want to track-that, by adding the ‘*’ marker. Eg in the paycheck transaction above,-insert ‘*’ between ‘2020-01-15’ and ‘paycheck’-- If you’re using version control, this can be another good time to-commit:--$ git commit -m 'txns' 2020.journal---File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS--25.7 Reporting-==============--Here are some basic reports.-- Show all transactions:--$ hledger print-2020-01-01 * opening balances- assets:bank:checking $1000- assets:bank:savings $2000- assets:cash $100- liabilities:creditcard $-50- equity:opening/closing balances $-3050--2020-01-10 * gift received- assets:cash $20- income:gifts--2020-01-12 * farmers market- expenses:food $13- assets:cash--2020-01-15 * paycheck- income:salary- assets:bank:checking $1000--2020-01-16 * adjust cash- assets:cash $-2 = $105- expenses:misc-- Show account names, and their hierarchy:--$ hledger accounts --tree-assets- bank- checking- savings- cash-equity- opening/closing balances-expenses- food- misc-income- gifts- salary-liabilities- creditcard-- Show all account totals:--$ hledger balance- $4105 assets- $4000 bank- $2000 checking- $2000 savings- $105 cash- $-3050 equity:opening/closing balances- $15 expenses- $13 food- $2 misc- $-1020 income- $-20 gifts- $-1000 salary- $-50 liabilities:creditcard---------------------- 0-- Show only asset and liability balances, as a flat list, limited to-depth 2:--$ hledger bal assets liabilities -2- $4000 assets:bank- $105 assets:cash- $-50 liabilities:creditcard---------------------- $4055-- Show the same thing without negative numbers, formatted as a simple-balance sheet:--$ hledger bs -2-Balance Sheet 2020-01-16-- || 2020-01-16 -========================++============- Assets || -------------------------++------------- assets:bank || $4000 - assets:cash || $105 -------------------------++------------- || $4105 -========================++============- Liabilities || -------------------------++------------- liabilities:creditcard || $50 -------------------------++------------- || $50 -========================++============- Net: || $4055 -- The final total is your "net worth" on the end date. (Or use ‘bse’-for a full balance sheet with equity.)-- Show income and expense totals, formatted as an income statement:--hledger is -Income Statement 2020-01-01-2020-01-16-- || 2020-01-01-2020-01-16 -===============++=======================- Revenues || ----------------++------------------------ income:gifts || $20 - income:salary || $1000 ----------------++------------------------ || $1020 -===============++=======================- Expenses || ----------------++------------------------ expenses:food || $13 - expenses:misc || $2 ----------------++------------------------ || $15 -===============++=======================- Net: || $1005 -- The final total is your net income during this period.-- Show transactions affecting your wallet, with running total:--$ hledger register cash-2020-01-01 opening balances assets:cash $100 $100-2020-01-10 gift received assets:cash $20 $120-2020-01-12 farmers market assets:cash $-13 $107-2020-01-16 adjust cash assets:cash $-2 $105-- Show weekly posting counts as a bar chart:--$ hledger activity -W-2019-12-30 *****-2020-01-06 ****-2020-01-13 ****---File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS--25.8 Migrating to a new file-============================--At the end of the year, you may want to continue your journal in a new-file, so that old transactions don’t slow down or clutter your reports,-and to help ensure the integrity of your accounting history. See the-close command.-- If using version control, don’t forget to ‘git add’ the new file.---Tag Table:-Node: Top210-Node: PART 1 USER INTERFACE3944-Ref: #part-1-user-interface4085-Node: Options4085-Ref: #options4204-Node: General options4346-Ref: #general-options4471-Node: Command options8921-Ref: #command-options9072-Node: Command arguments9488-Ref: #command-arguments9646-Node: Special characters10548-Ref: #special-characters10711-Node: Single escaping shell metacharacters10874-Ref: #single-escaping-shell-metacharacters11115-Node: Double escaping regular expression metacharacters11750-Ref: #double-escaping-regular-expression-metacharacters12061-Node: Triple escaping for add-on commands12631-Ref: #triple-escaping-for-add-on-commands12891-Node: Less escaping13559-Ref: #less-escaping13713-Node: Unicode characters14051-Ref: #unicode-characters14216-Node: Regular expressions15648-Ref: #regular-expressions15788-Node: Environment17642-Ref: #environment17753-Node: Input19364-Ref: #input19464-Node: Data formats20027-Ref: #data-formats20140-Node: Multiple files21592-Ref: #multiple-files21729-Node: Strict mode22214-Ref: #strict-mode22324-Node: Commands23078-Ref: #commands23179-Node: Add-on commands23663-Ref: #add-on-commands23765-Node: Output24932-Ref: #output25035-Node: Output destination25151-Ref: #output-destination25282-Node: Output format25711-Ref: #output-format25857-Node: CSV output27429-Ref: #csv-output27545-Node: HTML output27650-Ref: #html-output27788-Node: JSON output27888-Ref: #json-output28026-Node: SQL output28958-Ref: #sql-output29074-Node: Commodity styles29597-Ref: #commodity-styles29737-Node: Colour30344-Ref: #colour30462-Node: Box-drawing30896-Ref: #box-drawing31020-Node: Debug output31334-Ref: #debug-output31445-Node: Limitations32120-Ref: #limitations32240-Node: Troubleshooting33015-Ref: #troubleshooting33156-Node: PART 2 DATA FORMATS35678-Ref: #part-2-data-formats35825-Node: Journal35825-Ref: #journal35936-Node: Journal cheatsheet36579-Ref: #journal-cheatsheet36720-Node: About journal format40708-Ref: #about-journal-format40870-Node: Comments42408-Ref: #comments42540-Node: Transactions43394-Ref: #transactions43519-Node: Dates44553-Ref: #dates44662-Node: Simple dates44707-Ref: #simple-dates44825-Node: Posting dates45357-Ref: #posting-dates45477-Node: Status46460-Ref: #status46563-Node: Code48315-Ref: #code48420-Node: Description48652-Ref: #description48785-Node: Payee and note49107-Ref: #payee-and-note49215-Node: Transaction comments49562-Ref: #transaction-comments49717-Node: Postings50088-Ref: #postings50223-Node: Account names51232-Ref: #account-names51364-Node: Amounts53066-Ref: #amounts53183-Node: Decimal marks digit group marks54172-Ref: #decimal-marks-digit-group-marks54349-Node: Commodity55373-Ref: #commodity55562-Node: Directives influencing number parsing and display56544-Ref: #directives-influencing-number-parsing-and-display56805-Node: Commodity display style57267-Ref: #commodity-display-style57475-Node: Rounding59686-Ref: #rounding59806-Node: Costs60107-Ref: #costs60225-Node: Other cost/lot notations62256-Ref: #other-costlot-notations62390-Node: Balance assertions65143-Ref: #balance-assertions65296-Node: Assertions and ordering66389-Ref: #assertions-and-ordering66580-Node: Assertions and multiple included files67282-Ref: #assertions-and-multiple-included-files67544-Node: Assertions and multiple -f files68052-Ref: #assertions-and-multiple--f-files68305-Node: Assertions and commodities68714-Ref: #assertions-and-commodities68938-Node: Assertions and prices70128-Ref: #assertions-and-prices70336-Node: Assertions and subaccounts70767-Ref: #assertions-and-subaccounts70990-Node: Assertions and virtual postings71332-Ref: #assertions-and-virtual-postings71572-Node: Assertions and auto postings71712-Ref: #assertions-and-auto-postings71944-Node: Assertions and precision72615-Ref: #assertions-and-precision72799-Node: Posting comments73066-Ref: #posting-comments73214-Node: Tags73599-Ref: #tags73715-Node: Tag values74920-Ref: #tag-values75011-Node: Directives75784-Ref: #directives75913-Node: Directive effects77781-Ref: #directive-effects77937-Node: Directives and multiple files81020-Ref: #directives-and-multiple-files81200-Node: account directive81910-Ref: #account-directive82072-Node: Account comments83492-Ref: #account-comments83644-Node: Account subdirectives84164-Ref: #account-subdirectives84357-Node: Account error checking84499-Ref: #account-error-checking84699-Node: Account display order85918-Ref: #account-display-order86108-Node: Account types87247-Ref: #account-types87390-Node: alias directive91125-Ref: #alias-directive91292-Node: Basic aliases92352-Ref: #basic-aliases92485-Node: Regex aliases93239-Ref: #regex-aliases93398-Node: Combining aliases94292-Ref: #combining-aliases94472-Node: Aliases and multiple files95766-Ref: #aliases-and-multiple-files95972-Node: end aliases directive96557-Ref: #end-aliases-directive96782-Node: Aliases can generate bad account names96931-Ref: #aliases-can-generate-bad-account-names97181-Node: Aliases and account types97778-Ref: #aliases-and-account-types97972-Node: commodity directive98674-Ref: #commodity-directive98854-Node: Commodity error checking101458-Ref: #commodity-error-checking101606-Node: decimal-mark directive102135-Ref: #decimal-mark-directive102323-Node: include directive102724-Ref: #include-directive102894-Node: P directive103842-Ref: #p-directive103993-Node: payee directive104892-Ref: #payee-directive105047-Node: tag directive105367-Ref: #tag-directive105528-Node: Periodic transactions106000-Ref: #periodic-transactions106166-Node: Periodic rule syntax107904-Ref: #periodic-rule-syntax108084-Node: Periodic rules and relative dates108739-Ref: #periodic-rules-and-relative-dates109007-Node: Two spaces between period expression and description!109546-Ref: #two-spaces-between-period-expression-and-description109825-Node: Other syntax110515-Ref: #other-syntax110641-Node: Auto postings111286-Ref: #auto-postings111422-Node: Auto postings and multiple files113933-Ref: #auto-postings-and-multiple-files114135-Node: Auto postings and dates114352-Ref: #auto-postings-and-dates114624-Node: Auto postings and transaction balancing / inferred amounts / balance assertions114799-Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions115138-Node: Auto posting tags115645-Ref: #auto-posting-tags115858-Node: Balance assignments116520-Ref: #balance-assignments116700-Node: Balance assignments and prices118034-Ref: #balance-assignments-and-prices118204-Node: Bracketed posting dates118415-Ref: #bracketed-posting-dates118601-Node: D directive119145-Ref: #d-directive119319-Node: apply account directive120987-Ref: #apply-account-directive121173-Node: Y directive121872-Ref: #y-directive122038-Node: Secondary dates122882-Ref: #secondary-dates123038-Node: Star comments123870-Ref: #star-comments124032-Node: Valuation expressions124572-Ref: #valuation-expressions124751-Node: Virtual postings124873-Ref: #virtual-postings125054-Node: Other Ledger directives126626-Ref: #other-ledger-directives126791-Node: CSV127361-Ref: #csv127454-Node: CSV rules cheatsheet129557-Ref: #csv-rules-cheatsheet129689-Node: separator131457-Ref: #separator131588-Node: skip132166-Ref: #skip132278-Node: date-format132861-Ref: #date-format132986-Node: timezone133732-Ref: #timezone133859-Node: newest-first134892-Ref: #newest-first135034-Node: intra-day-reversed135618-Ref: #intra-day-reversed135776-Node: decimal-mark136273-Ref: #decimal-mark136418-Node: fields list136757-Ref: #fields-list136898-Node: Field assignment138621-Ref: #field-assignment138765-Node: Field names139814-Ref: #field-names139945-Node: date field141166-Ref: #date-field141284-Node: date2 field141336-Ref: #date2-field141477-Node: status field141539-Ref: #status-field141682-Node: code field141737-Ref: #code-field141882-Node: description field141933-Ref: #description-field142093-Node: comment field142158-Ref: #comment-field142313-Node: account field142626-Ref: #account-field142776-Node: amount field143372-Ref: #amount-field143521-Node: currency field145626-Ref: #currency-field145779-Node: balance field146048-Ref: #balance-field146180-Node: if block146568-Ref: #if-block146693-Node: Matchers148117-Ref: #matchers148231-Node: if table149761-Ref: #if-table149887-Node: balance-type151323-Ref: #balance-type151456-Node: include152164-Ref: #include152295-Node: Working with CSV152745-Ref: #working-with-csv152892-Node: Rapid feedback153263-Ref: #rapid-feedback153396-Node: Valid CSV153852-Ref: #valid-csv153998-Node: File Extension154752-Ref: #file-extension154925-Node: Reading CSV from standard input155515-Ref: #reading-csv-from-standard-input155739-Node: Reading multiple CSV files155905-Ref: #reading-multiple-csv-files156123-Node: Valid transactions156372-Ref: #valid-transactions156566-Node: Deduplicating importing157194-Ref: #deduplicating-importing157389-Node: Setting amounts158435-Ref: #setting-amounts158606-Node: Amount signs161129-Ref: #amount-signs161297-Node: Setting currency/commodity162036-Ref: #setting-currencycommodity162240-Node: Amount decimal places163432-Ref: #amount-decimal-places163638-Node: Referencing other fields163956-Ref: #referencing-other-fields164169-Node: How CSV rules are evaluated165072-Ref: #how-csv-rules-are-evaluated165289-Node: Well factored rules166802-Ref: #well-factored-rules166970-Node: CSV rules examples167308-Ref: #csv-rules-examples167443-Node: Bank of Ireland167508-Ref: #bank-of-ireland167645-Node: Coinbase169113-Ref: #coinbase169251-Node: Amazon170304-Ref: #amazon170429-Node: Paypal172154-Ref: #paypal172262-Node: Timeclock179908-Ref: #timeclock180013-Node: Timedot182181-Ref: #timedot182304-Node: PART 3 REPORTING CONCEPTS187155-Ref: #part-3-reporting-concepts187319-Node: Time periods187319-Ref: #time-periods187453-Node: Report start & end date187571-Ref: #report-start-end-date187723-Node: Smart dates189456-Ref: #smart-dates189609-Node: Report intervals191569-Ref: #report-intervals191724-Node: Date adjustment192176-Ref: #date-adjustment192336-Node: Period expressions193668-Ref: #period-expressions193809-Node: Period expressions with a report interval195645-Ref: #period-expressions-with-a-report-interval195879-Node: More complex report intervals196109-Ref: #more-complex-report-intervals196354-Node: Multiple weekday intervals198283-Ref: #multiple-weekday-intervals198472-Node: Depth199336-Ref: #depth199438-Node: Queries199758-Ref: #queries199860-Node: Query types200805-Ref: #query-types200926-Node: Combining query terms204266-Ref: #combining-query-terms204443-Node: Queries and command options205541-Ref: #queries-and-command-options205740-Node: Queries and valuation206005-Ref: #queries-and-valuation206200-Node: Querying with account aliases206439-Ref: #querying-with-account-aliases206650-Node: Querying with cost or value206792-Ref: #querying-with-cost-or-value206969-Node: Pivoting207278-Ref: #pivoting207392-Node: Generating data208880-Ref: #generating-data209012-Node: Forecasting209510-Ref: #forecasting209635-Node: Budgeting212522-Ref: #budgeting212642-Node: Cost reporting212913-Ref: #cost-reporting213041-Node: -B Convert to cost214156-Ref: #b-convert-to-cost214312-Node: Equity conversion postings215720-Ref: #equity-conversion-postings215934-Node: Inferring equity postings from cost216829-Ref: #inferring-equity-postings-from-cost217078-Node: Inferring cost from equity postings217897-Ref: #inferring-cost-from-equity-postings218145-Node: When to infer cost/equity219954-Ref: #when-to-infer-costequity220172-Node: How to record conversions220580-Ref: #how-to-record-conversions220772-Node: Conversion with implicit cost221063-Ref: #conversion-with-implicit-cost221268-Node: Conversion with explicit cost222173-Ref: #conversion-with-explicit-cost222418-Node: Conversion with equity postings222845-Ref: #conversion-with-equity-postings223114-Node: Conversion with equity postings and explicit cost223951-Ref: #conversion-with-equity-postings-and-explicit-cost224218-Node: Cost tips224692-Ref: #cost-tips224818-Node: Valuation225554-Ref: #valuation225678-Node: -V Value226464-Ref: #v-value226590-Node: -X Value in specified commodity226789-Ref: #x-value-in-specified-commodity226984-Node: Valuation date227141-Ref: #valuation-date227312-Node: Finding market price227751-Ref: #finding-market-price227956-Node: --infer-market-prices market prices from transactions229136-Ref: #infer-market-prices-market-prices-from-transactions229414-Node: Valuation commodity232260-Ref: #valuation-commodity232473-Node: Simple valuation examples233718-Ref: #simple-valuation-examples233916-Node: --value Flexible valuation234579-Ref: #value-flexible-valuation234785-Node: More valuation examples236471-Ref: #more-valuation-examples236680-Node: Interaction of valuation and queries238691-Ref: #interaction-of-valuation-and-queries238932-Node: Effect of valuation on reports239412-Ref: #effect-of-valuation-on-reports239609-Node: PART 4 COMMANDS247368-Ref: #part-4-commands247511-Node: Commands overview247881-Ref: #commands-overview248015-Node: DATA ENTRY248194-Ref: #data-entry248318-Node: DATA CREATION248521-Ref: #data-creation248675-Node: DATA MANAGEMENT248799-Ref: #data-management248964-Node: REPORTS FINANCIAL249089-Ref: #reports-financial249264-Node: REPORTS VERSATILE249579-Ref: #reports-versatile249752-Node: REPORTS BASIC250013-Ref: #reports-basic250165-Node: HELP250698-Ref: #help250820-Node: ADD-ONS250879-Ref: #add-ons250985-Node: accounts251582-Ref: #accounts251715-Node: activity253690-Ref: #activity253809-Node: add254183-Ref: #add254293-Node: aregister257154-Ref: #aregister257275-Node: aregister and custom posting dates260251-Ref: #aregister-and-custom-posting-dates260417-Node: balance260985-Ref: #balance261111-Node: balance features262116-Ref: #balance-features262256-Node: Simple balance report264386-Ref: #simple-balance-report264571-Node: Balance report line format266216-Ref: #balance-report-line-format266418-Node: Filtered balance report268668-Ref: #filtered-balance-report268860-Node: List or tree mode269187-Ref: #list-or-tree-mode269355-Node: Depth limiting270730-Ref: #depth-limiting270896-Node: Dropping top-level accounts271513-Ref: #dropping-top-level-accounts271713-Node: Showing declared accounts272027-Ref: #showing-declared-accounts272226-Node: Sorting by amount272767-Ref: #sorting-by-amount272934-Node: Percentages273624-Ref: #percentages273783-Node: Multi-period balance report274353-Ref: #multi-period-balance-report274553-Node: Balance change end balance276946-Ref: #balance-change-end-balance277155-Node: Balance report types278603-Ref: #balance-report-types278784-Node: Calculation type279300-Ref: #calculation-type279455-Node: Accumulation type279986-Ref: #accumulation-type280166-Node: Valuation type281094-Ref: #valuation-type281282-Node: Combining balance report types282349-Ref: #combining-balance-report-types282543-Node: Budget report284447-Ref: #budget-report284599-Node: Budget report start date290333-Ref: #budget-report-start-date290511-Node: Budgets and subaccounts291873-Ref: #budgets-and-subaccounts292080-Node: Selecting budget goals295566-Ref: #selecting-budget-goals295765-Node: Budget vs forecast296812-Ref: #budget-vs-forecast296971-Node: Data layout298671-Ref: #data-layout298821-Node: Useful balance reports306762-Ref: #useful-balance-reports306912-Node: balancesheet308065-Ref: #balancesheet308210-Node: balancesheetequity309576-Ref: #balancesheetequity309734-Node: cashflow311177-Ref: #cashflow311308-Node: check312794-Ref: #check312908-Node: Basic checks313714-Ref: #basic-checks313834-Node: Strict checks314372-Ref: #strict-checks314515-Node: Other checks314956-Ref: #other-checks315098-Node: Custom checks315675-Ref: #custom-checks315832-Node: More about specific checks316253-Ref: #more-about-specific-checks316415-Node: close317147-Ref: #close317258-Node: close and costs319896-Ref: #close-and-costs320040-Node: close and balance assertions320329-Ref: #close-and-balance-assertions320531-Node: Example retain earnings321702-Ref: #example-retain-earnings321919-Node: Example migrate balances to a new file322277-Ref: #example-migrate-balances-to-a-new-file322542-Node: Example excluding closing/opening transactions323095-Ref: #example-excluding-closingopening-transactions323344-Node: codes324522-Ref: #codes324639-Node: commodities325515-Ref: #commodities325651-Node: descriptions325721-Ref: #descriptions325858-Node: diff326149-Ref: #diff326264-Node: files327310-Ref: #files327419-Node: help327560-Ref: #help-1327669-Node: import328659-Ref: #import328782-Node: Deduplication329890-Ref: #deduplication330015-Node: Import testing331937-Ref: #import-testing332102-Node: Importing balance assignments332953-Ref: #importing-balance-assignments333159-Node: Commodity display styles333816-Ref: #commodity-display-styles333989-Node: incomestatement334118-Ref: #incomestatement334260-Node: notes335627-Ref: #notes335749-Node: payees336111-Ref: #payees336226-Node: prices336751-Ref: #prices336866-Node: print337168-Ref: #print337283-Node: register342729-Ref: #register342851-Node: Custom register output347960-Ref: #custom-register-output348091-Node: rewrite349466-Ref: #rewrite349584-Node: Re-write rules in a file351496-Ref: #re-write-rules-in-a-file351659-Node: Diff output format352812-Ref: #diff-output-format352995-Node: rewrite vs print --auto354107-Ref: #rewrite-vs.-print---auto354269-Node: roi354843-Ref: #roi354950-Node: Spaces and special characters in --inv and --pnl356711-Ref: #spaces-and-special-characters-in---inv-and---pnl356959-Node: Semantics of --inv and --pnl357457-Ref: #semantics-of---inv-and---pnl357704-Node: IRR and TWR explained359582-Ref: #irr-and-twr-explained359742-Node: stats362854-Ref: #stats362962-Node: tags364359-Ref: #tags-1364466-Node: test365483-Ref: #test365576-Node: PART 5 COMMON TASKS366326-Ref: #part-5-common-tasks366459-Node: Getting help366733-Ref: #getting-help366874-Node: Constructing command lines367638-Ref: #constructing-command-lines367839-Node: Starting a journal file368520-Ref: #starting-a-journal-file368727-Node: Setting opening balances369925-Ref: #setting-opening-balances370130-Node: Recording transactions373283-Ref: #recording-transactions373472-Node: Reconciling374028-Ref: #reconciling374180-Node: Reporting376493-Ref: #reporting376642-Node: Migrating to a new file380631-Ref: #migrating-to-a-new-file380788+ This manual is for hledger’s command line interface, version 1.29.1.+It also describes the common options, file formats and concepts used by+all hledger programs. It might accidentally teach you some+bookkeeping/accounting as well! You don’t need to know everything in+here to use hledger productively, but when you have a question about+functionality, this doc should answer it. It is detailed, so do skip+ahead or skim when needed. You can read it on hledger.org, or as an+info manual or man page on your system. You can also get it from+hledger itself with+‘hledger --man’, ‘hledger --info’ or ‘hledger help [TOPIC]’.++ The main function of the hledger CLI is to read plain text files+describing financial transactions, crunch the numbers, and print a+useful report on the terminal (or save it as HTML, CSV, JSON or SQL).+Many reports are available, as subcommands. hledger will also detect+other ‘hledger-*’ executables as extra subcommands.++ hledger reads data from one or more files in journal, timeclock,+timedot, or CSV format. The default file is ‘.hledger.journal’ in your+home directory; this can be overridden with one or more ‘-f FILE’+options, or the ‘LEDGER_FILE’ environment variable. hledger CLI can+also read from stdin with ‘-f-’; more on that below.++ Here is a small but valid hledger journal file describing one+transaction:++2015-10-16 bought food+ expenses:food $10+ assets:cash++ Transactions are dated movements of money (etc.) between two or more+_accounts_: bank accounts, your wallet, revenue/expense categories,+people, etc. You can choose any account names you wish, using ‘:’ to+indicate subaccounts. There must be at least two spaces between account+name and amount. Positive amounts are inflow to that account (_debit_),+negatives are outflow from it (_credit_). (Some reports show revenue,+liability and equity account balances as negative numbers as a result;+this is normal.)++ hledger’s add command can help you add transactions, or you can+install other data entry UIs like hledger-web or hledger-iadd. For more+extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM++ vim-ledger, or VS Code + hledger-vscode are some good choices (see+https://hledger.org/editors.html).++ To get started, run ‘hledger add’ and follow the prompts, or save+some entries like the above in ‘$HOME/.hledger.journal’, then try+commands like:+‘hledger print -x’+‘hledger aregister assets’+‘hledger balance’+‘hledger balancesheet’+‘hledger incomestatement’.+Run ‘hledger’ to list the commands. See also the "Starting a journal+file" and "Setting opening balances" sections in PART 5: COMMON TASKS.++* Menu:++* PART 1 USER INTERFACE::+* Options::+* Environment::+* Input::+* Commands::+* Output::+* Limitations::+* Troubleshooting::+* PART 2 DATA FORMATS::+* Journal::+* CSV::+* Timeclock::+* Timedot::+* PART 3 REPORTING CONCEPTS::+* Time periods::+* Depth::+* Queries::+* Pivoting::+* Generating data::+* Forecasting::+* Budgeting::+* Cost reporting::+* Valuation::+* PART 4 COMMANDS::+* PART 5 COMMON TASKS::+++File: hledger.info, Node: PART 1 USER INTERFACE, Next: Options, Prev: Top, Up: Top++1 PART 1: USER INTERFACE+************************+++File: hledger.info, Node: Options, Next: Environment, Prev: PART 1 USER INTERFACE, Up: Top++2 Options+*********++* Menu:++* General options::+* Command options::+* Command arguments::+* Special characters::+* Unicode characters::+* Regular expressions::+++File: hledger.info, Node: General options, Next: Command options, Up: Options++2.1 General options+===================++To see general usage help, including general options which are supported+by most hledger commands, run ‘hledger -h’.++ General help options:++‘-h --help’++ show general or COMMAND help+‘--man’++ show general or COMMAND user manual with man+‘--info’++ show general or COMMAND user manual with info+‘--version’++ show general or ADDONCMD version+‘--debug[=N]’++ show debug output (levels 1-9, default: 1)++ General input options:++‘-f FILE --file=FILE’++ use a different input file. For stdin, use - (default:+ ‘$LEDGER_FILE’ or ‘$HOME/.hledger.journal’)+‘--rules-file=RULESFILE’++ Conversion rules file to use when reading CSV (default: FILE.rules)+‘--separator=CHAR’++ Field separator to expect when reading CSV (default: ’,’)+‘--alias=OLD=NEW’++ rename accounts named OLD to NEW+‘--anon’++ anonymize accounts and payees+‘--pivot FIELDNAME’++ use some other field or tag for the account name+‘-I --ignore-assertions’++ disable balance assertion checks (note: does not disable balance+ assignments)+‘-s --strict’++ do extra error checking (check that all posted accounts are+ declared)++ General reporting options:++‘-b --begin=DATE’++ include postings/txns on or after this date (will be adjusted to+ preceding subperiod start when using a report interval)+‘-e --end=DATE’++ include postings/txns before this date (will be adjusted to+ following subperiod end when using a report interval)+‘-D --daily’++ multiperiod/multicolumn report by day+‘-W --weekly’++ multiperiod/multicolumn report by week+‘-M --monthly’++ multiperiod/multicolumn report by month+‘-Q --quarterly’++ multiperiod/multicolumn report by quarter+‘-Y --yearly’++ multiperiod/multicolumn report by year+‘-p --period=PERIODEXP’++ set start date, end date, and/or reporting interval all at once+ using period expressions syntax+‘--date2’++ match the secondary date instead (see command help for other+ effects)+‘--today=DATE’++ override today’s date (affects relative smart dates, for+ tests/examples)+‘-U --unmarked’++ include only unmarked postings/txns (can combine with -P or -C)+‘-P --pending’++ include only pending postings/txns+‘-C --cleared’++ include only cleared postings/txns+‘-R --real’++ include only non-virtual postings+‘-NUM --depth=NUM’++ hide/aggregate accounts or postings more than NUM levels deep+‘-E --empty’++ show items with zero amount, normally hidden (and vice-versa in+ hledger-ui/hledger-web)+‘-B --cost’++ convert amounts to their cost/selling amount at transaction time+‘-V --market’++ convert amounts to their market value in default valuation+ commodities+‘-X --exchange=COMM’++ convert amounts to their market value in commodity COMM+‘--value’++ convert amounts to cost or market value, more flexibly than+ -B/-V/-X+‘--infer-market-prices’++ use transaction prices (recorded with @ or @@) as additional market+ prices, as if they were P directives+‘--auto’++ apply automated posting rules to modify transactions.+‘--forecast’++ generate future transactions from periodic transaction rules, for+ the next 6 months or till report end date. In hledger-ui, also+ make ordinary future transactions visible.+‘--commodity-style’++ Override the commodity style in the output for the specified+ commodity. For example ’EUR1.000,00’.+‘--color=WHEN (or --colour=WHEN)’++ Should color-supporting commands use ANSI color codes in text+ output. ’auto’ (default): whenever stdout seems to be a+ color-supporting terminal. ’always’ or ’yes’: always, useful eg+ when piping output into ’less -R’. ’never’ or ’no’: never. A+ NO_COLOR environment variable overrides this.+‘--pretty[=WHEN]’++ Show prettier output, e.g. using unicode box-drawing characters.+ Accepts ’yes’ (the default) or ’no’ (’y’, ’n’, ’always’, ’never’+ also work). If you provide an argument you must use ’=’, e.g.+ ’–pretty=yes’.++ When a reporting option appears more than once in the command line,+the last one takes precedence.++ Some reporting options can also be written as query arguments.+++File: hledger.info, Node: Command options, Next: Command arguments, Prev: General options, Up: Options++2.2 Command options+===================++To see options for a particular command, including command-specific+options, run: ‘hledger COMMAND -h’.++ Command-specific options must be written after the command name, eg:+‘hledger print -x’.++ Additionally, if the command is an add-on, you may need to put its+options after a double-hyphen, eg: ‘hledger ui -- --watch’. Or, you can+run the add-on executable directly: ‘hledger-ui --watch’.+++File: hledger.info, Node: Command arguments, Next: Special characters, Prev: Command options, Up: Options++2.3 Command arguments+=====================++Most hledger commands accept arguments after the command name, which are+often a query, filtering the data in some way.++ You can save a set of command line options/arguments in a file, and+then reuse them by writing ‘@FILENAME’ as a command line argument. Eg:+‘hledger bal @foo.args’. (To prevent this, eg if you have an argument+that begins with a literal ‘@’, precede it with ‘--’, eg: ‘hledger bal+-- @ARG’).++ Inside the argument file, each line should contain just one option or+argument. Avoid the use of spaces, except inside quotes (or you’ll see+a confusing error). Between a flag and its argument, use = (or+nothing). Bad:++assets depth:2+-X USD++ Good:++assets+depth:2+-X=USD++ For special characters (see below), use one less level of quoting+than you would at the command prompt. Bad:++-X"$"++ Good:++-X$++ See also: Save frequently used options.+++File: hledger.info, Node: Special characters, Next: Unicode characters, Prev: Command arguments, Up: Options++2.4 Special characters+======================++* Menu:++* Single escaping shell metacharacters::+* Double escaping regular expression metacharacters::+* Triple escaping for add-on commands::+* Less escaping::+++File: hledger.info, Node: Single escaping shell metacharacters, Next: Double escaping regular expression metacharacters, Up: Special characters++2.4.1 Single escaping (shell metacharacters)+--------------------------------------------++In shell command lines, characters significant to your shell - such as+spaces, ‘<’, ‘>’, ‘(’, ‘)’, ‘|’, ‘$’ and ‘\’ - should be "shell-escaped"+if you want hledger to see them. This is done by enclosing them in+single or double quotes, or by writing a backslash before them. Eg to+match an account name containing a space:++$ hledger register 'credit card'++ or:++$ hledger register credit\ card++ Windows users should keep in mind that ‘cmd’ treats single quote as a+regular character, so you should be using double quotes exclusively.+PowerShell treats both single and double quotes as quotes.+++File: hledger.info, Node: Double escaping regular expression metacharacters, Next: Triple escaping for add-on commands, Prev: Single escaping shell metacharacters, Up: Special characters++2.4.2 Double escaping (regular expression metacharacters)+---------------------------------------------------------++Characters significant in regular expressions (described below) - such+as ‘.’, ‘^’, ‘$’, ‘[’, ‘]’, ‘(’, ‘)’, ‘|’, and ‘\’ - may need to be+"regex-escaped" if you don’t want them to be interpreted by hledger’s+regular expression engine. This is done by writing backslashes before+them, but since backslash is typically also a shell metacharacter, both+shell-escaping and regex-escaping will be needed. Eg to match a literal+‘$’ sign while using the bash shell:++$ hledger balance cur:'\$'++ or:++$ hledger balance cur:\\$+++File: hledger.info, Node: Triple escaping for add-on commands, Next: Less escaping, Prev: Double escaping regular expression metacharacters, Up: Special characters++2.4.3 Triple escaping (for add-on commands)+-------------------------------------------++When you use hledger to run an external add-on command (described+below), one level of shell-escaping is lost from any options or+arguments intended for by the add-on command, so those need an extra+level of shell-escaping. Eg to match a literal ‘$’ sign while using the+bash shell and running an add-on command (‘ui’):++$ hledger ui cur:'\\$'++ or:++$ hledger ui cur:\\\\$++ If you wondered why _four_ backslashes, perhaps this helps:++unescaped: ‘$’+escaped: ‘\$’+double-escaped: ‘\\$’+triple-escaped: ‘\\\\$’++ Or, you can avoid the extra escaping by running the add-on executable+directly:++$ hledger-ui cur:\\$+++File: hledger.info, Node: Less escaping, Prev: Triple escaping for add-on commands, Up: Special characters++2.4.4 Less escaping+-------------------++Options and arguments are sometimes used in places other than the shell+command line, where shell-escaping is not needed, so there you should+use one less level of escaping. Those places include:++ • an @argumentfile+ • hledger-ui’s filter field+ • hledger-web’s search form+ • GHCI’s prompt (used by developers).+++File: hledger.info, Node: Unicode characters, Next: Regular expressions, Prev: Special characters, Up: Options++2.5 Unicode characters+======================++hledger is expected to handle non-ascii characters correctly:++ • they should be parsed correctly in input files and on the command+ line, by all hledger tools (add, iadd, hledger-web’s+ search/add/edit forms, etc.)++ • they should be displayed correctly by all hledger tools, and+ on-screen alignment should be preserved.++ This requires a well-configured environment. Here are some tips:++ • A system locale must be configured, and it must be one that can+ decode the characters being used. In bash, you can set a locale+ like this: ‘export LANG=en_US.UTF-8’. There are some more details+ in Troubleshooting. This step is essential - without it, hledger+ will quit on encountering a non-ascii character (as with all+ GHC-compiled programs).++ • your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)+ must support unicode++ • the terminal must be using a font which includes the required+ unicode glyphs++ • the terminal should be configured to display wide characters as+ double width (for report alignment)++ • on Windows, for best results you should run hledger in the same+ kind of environment in which it was built. Eg hledger built in the+ standard CMD.EXE environment (like the binaries on our download+ page) might show display problems when run in a cygwin or msys+ terminal, and vice versa. (See eg #961).+++File: hledger.info, Node: Regular expressions, Prev: Unicode characters, Up: Options++2.6 Regular expressions+=======================++hledger uses regular expressions in a number of places:++ • query terms, on the command line and in the hledger-web search+ form: ‘REGEX’, ‘desc:REGEX’, ‘cur:REGEX’, ‘tag:...=REGEX’+ • CSV rules conditional blocks: ‘if REGEX ...’+ • account alias directive and ‘--alias’ option: ‘alias /REGEX/ =+ REPLACEMENT’, ‘--alias /REGEX/=REPLACEMENT’++ hledger’s regular expressions come from the regex-tdfa library. If+they’re not doing what you expect, it’s important to know exactly what+they support:++ 1. they are case insensitive+ 2. they are infix matching (they do not need to match the entire thing+ being matched)+ 3. they are POSIX ERE (extended regular expressions)+ 4. they also support GNU word boundaries (‘\b’, ‘\B’, ‘\<’, ‘\>’)+ 5. they do not support backreferences; if you write ‘\1’, it will+ match the digit ‘1’. Except when doing text replacement, eg in+ account aliases, where backreferences can be used in the+ replacement string to reference capturing groups in the search+ regexp.+ 6. they do not support mode modifiers (‘(?s)’), character classes+ (‘\w’, ‘\d’), or anything else not mentioned above.++ Some things to note:++ • In the ‘alias’ directive and ‘--alias’ option, regular expressions+ must be enclosed in forward slashes (‘/REGEX/’). Elsewhere in+ hledger, these are not required.++ • In queries, to match a regular expression metacharacter like ‘$’ as+ a literal character, prepend a backslash. Eg to search for amounts+ with the dollar sign in hledger-web, write ‘cur:\$’.++ • On the command line, some metacharacters like ‘$’ have a special+ meaning to the shell and so must be escaped at least once more.+ See Special characters.+++File: hledger.info, Node: Environment, Next: Input, Prev: Options, Up: Top++3 Environment+*************++*LEDGER_FILE* The journal file path when not specified with ‘-f’.++ On unix computers, the default value is: ‘~/.hledger.journal’.++ A more typical value is something like ‘~/finance/YYYY.journal’,+where ‘~/finance’ is a version-controlled finance directory and YYYY is+the current year. Or, ‘~/finance/current.journal’, where+current.journal is a symbolic link to YYYY.journal.++ The usual way to set this permanently is to add a command to one of+your shell’s startup files (eg ‘~/.profile’):++export LEDGER_FILE=~/finance/current.journal`++ On some Mac computers, there is a more thorough way to set+environment variables, that will also affect applications started from+the GUI (eg, Emacs started from a dock icon): In+‘~/.MacOSX/environment.plist’, add an entry like:++{+ "LEDGER_FILE" : "~/finance/current.journal"+}++ For this to take effect you might need to ‘killall Dock’, or reboot.++ On Windows computers, the default value is probably+‘C:\Users\YOURNAME\.hledger.journal’. You can change this by running a+command like this in a powershell window (let us know if you need to be+an Administrator, and if this persists across a reboot):++> setx LEDGER_FILE "C:\Users\MyUserName\finance\2021.journal"++ Or, change it in settings: see+https://www.java.com/en/download/help/path.html.++ *COLUMNS* The screen width used by the register command. Default:+the full terminal width.++ *NO_COLOR* If this variable exists with any value, hledger will not+use ANSI color codes in terminal output. This is overriden by the+–color/–colour option.+++File: hledger.info, Node: Input, Next: Commands, Prev: Environment, Up: Top++4 Input+*******++hledger reads transactions from one or more data files. The default+data file is ‘$HOME/.hledger.journal’ (or on Windows, something like+‘C:\Users\YOURNAME\.hledger.journal’).++ You can override this with the ‘$LEDGER_FILE’ environment variable:++$ setenv LEDGER_FILE ~/finance/2016.journal+$ hledger stats++ or with one or more ‘-f/--file’ options:++$ hledger -f /some/file -f another_file stats++ The file name ‘-’ means standard input:++$ cat some.journal | hledger -f-++* Menu:++* Data formats::+* Multiple files::+* Strict mode::+++File: hledger.info, Node: Data formats, Next: Multiple files, Up: Input++4.1 Data formats+================++Usually the data file is in hledger’s journal format, but it can be in+any of the supported file formats, which currently are:++Reader: Reads: Used for file+ extensions:+--------------------------------------------------------------------------+‘journal’hledger journal files and some Ledger ‘.journal’ ‘.j’+ journals, for transactions ‘.hledger’ ‘.ledger’+‘timeclock’timeclock files, for precise time ‘.timeclock’+ logging+‘timedot’timedot files, for approximate time ‘.timedot’+ logging+‘csv’ comma/semicolon/tab/other-separated ‘.csv’ ‘.ssv’ ‘.tsv’+ values, for data import++ These formats are described in more detail below.++ hledger detects the format automatically based on the file extensions+shown above. If it can’t recognise the file extension, it assumes+‘journal’ format. So for non-journal files, it’s important to use a+recognised file extension, so as to either read successfully or to show+relevant error messages.++ You can also force a specific reader/format by prefixing the file+path with the format and a colon. Eg, to read a .dat file as csv+format:++$ hledger -f csv:/some/csv-file.dat stats++ Or to read stdin (‘-’) as timeclock format:++$ echo 'i 2009/13/1 08:00:00' | hledger print -ftimeclock:-+++File: hledger.info, Node: Multiple files, Next: Strict mode, Prev: Data formats, Up: Input++4.2 Multiple files+==================++You can specify multiple ‘-f’ options, to read multiple files as one big+journal. There are some limitations with this:++ • most directives do not affect sibling files+ • balance assertions will not see any account balances from previous+ files++ If you need either of those things, you can++ • use a single parent file which includes the others+ • or concatenate the files into one before reading, eg: ‘cat+ a.journal b.journal | hledger -f- CMD’.+++File: hledger.info, Node: Strict mode, Prev: Multiple files, Up: Input++4.3 Strict mode+===============++hledger checks input files for valid data. By default, the most+important errors are detected, while still accepting easy journal files+without a lot of declarations:++ • Are the input files parseable, with valid syntax ?+ • Are all transactions balanced ?+ • Do all balance assertions pass ?++ With the ‘-s’/‘--strict’ flag, additional checks are performed:++ • Are all accounts posted to, declared with an ‘account’ directive ?+ (Account error checking)+ • Are all commodities declared with a ‘commodity’ directive ?+ (Commodity error checking)+ • Are all commodity conversions declared explicitly ?++ You can use the check command to run individual checks – the ones+listed above and some more.+++File: hledger.info, Node: Commands, Next: Output, Prev: Input, Up: Top++5 Commands+**********++hledger provides a number of built-in subcommands (described below).+Most of these read your data without changing it, and display a report.+A few assist with data entry and management.++ Run ‘hledger’ with no arguments to list the commands available, and+‘hledger CMD’ to run a command. CMD can be the full command name, or+its standard abbreviation shown in the commands list, or any unambiguous+prefix of the name. Eg: ‘hledger bal’.++* Menu:++* Add-on commands::+++File: hledger.info, Node: Add-on commands, Up: Commands++5.1 Add-on commands+===================++Add-on commands are extra subcommands provided by programs or scripts in+your PATH++ • whose name starts with ‘hledger-’+ • whose name ends with a recognised file extension:+ ‘.bat’,‘.com’,‘.exe’, ‘.hs’,‘.lhs’,‘.pl’,‘.py’,‘.rb’,‘.rkt’,‘.sh’+ or none+ • and (on unix, mac) which are executable by the current user.++ Addons can be written in any language, but haskell scripts or+programs have a big advantage: they can use hledger’s library code, for+command-line options, parsing and reporting.++ Several add-on commands are installed by the hledger-install script.+See https://hledger.org/scripts.html for more details.++ Note in a hledger command line, add-on command flags must have a+double dash (‘--’) preceding them. Eg you must write:++$ hledger web -- --serve++ and not:++$ hledger web --serve++ (because the ‘--serve’ flag belongs to ‘hledger-web’, not ‘hledger’).++ The ‘-h/--help’ and ‘--version’ flags don’t require ‘--’.++ If you have any trouble with this, remember you can always run the+add-on program directly, eg:++$ hledger-web --serve+++File: hledger.info, Node: Output, Next: Limitations, Prev: Commands, Up: Top++6 Output+********++* Menu:++* Output destination::+* Output format::+* Commodity styles::+* Colour::+* Box-drawing::+* Debug output::+++File: hledger.info, Node: Output destination, Next: Output format, Up: Output++6.1 Output destination+======================++hledger commands send their output to the terminal by default. You can+of course redirect this, eg into a file, using standard shell syntax:++$ hledger print > foo.txt++ Some commands (print, register, stats, the balance commands) also+provide the ‘-o/--output-file’ option, which does the same thing without+needing the shell. Eg:++$ hledger print -o foo.txt+$ hledger print -o - # write to stdout (the default)+++File: hledger.info, Node: Output format, Next: Commodity styles, Prev: Output destination, Up: Output++6.2 Output format+=================++Some commands offer other kinds of output, not just text on the+terminal. Here are those commands and the formats currently supported:++- txt csv html json sql+-----------------------------------------------------------------------------+aregister Y Y Y Y+balance Y _1_ Y _1_ Y _1,2_ Y+balancesheet Y _1_ Y _1_ Y _1_ Y+balancesheetequity Y _1_ Y _1_ Y _1_ Y+cashflow Y _1_ Y _1_ Y _1_ Y+incomestatement Y _1_ Y _1_ Y _1_ Y+print Y Y Y Y+register Y Y Y++ • _1 Also affected by the balance commands’ ‘--layout’ option._+ • _2 ‘balance’ does not support html output without a report interval+ or with ‘--budget’._++ The output format is selected by the ‘-O/--output-format=FMT’ option:++$ hledger print -O csv # print CSV on stdout++ or by the filename extension of an output file specified with the+‘-o/--output-file=FILE.FMT’ option:++$ hledger balancesheet -o foo.csv # write CSV to foo.csv++ The ‘-O’ option can be combined with ‘-o’ to override the file+extension, if needed:++$ hledger balancesheet -o foo.txt -O csv # write CSV to foo.txt++ Some notes about the various output formats:++* Menu:++* CSV output::+* HTML output::+* JSON output::+* SQL output::+++File: hledger.info, Node: CSV output, Next: HTML output, Up: Output format++6.2.1 CSV output+----------------++ • In CSV output, digit group marks (such as thousands separators) are+ disabled automatically.+++File: hledger.info, Node: HTML output, Next: JSON output, Prev: CSV output, Up: Output format++6.2.2 HTML output+-----------------++ • HTML output can be styled by an optional ‘hledger.css’ file in the+ same directory.+++File: hledger.info, Node: JSON output, Next: SQL output, Prev: HTML output, Up: Output format++6.2.3 JSON output+-----------------++ • This is not yet much used; real-world feedback is welcome.++ • Our JSON is rather large and verbose, since it is a faithful+ representation of hledger’s internal data types. To understand the+ JSON, read the Haskell type definitions, which are mostly in+ https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.++ • hledger represents quantities as Decimal values storing up to 255+ significant digits, eg for repeating decimals. Such numbers can+ arise in practice (from automatically-calculated transaction+ prices), and would break most JSON consumers. So in JSON, we show+ quantities as simple Numbers with at most 10 decimal places. We+ don’t limit the number of integer digits, but that part is under+ your control. We hope this approach will not cause problems in+ practice; if you find otherwise, please let us know. (Cf #1195)+++File: hledger.info, Node: SQL output, Prev: JSON output, Up: Output format++6.2.4 SQL output+----------------++ • This is not yet much used; real-world feedback is welcome.++ • SQL output is expected to work with sqlite, MySQL and PostgreSQL++ • SQL output is structured with the expectations that statements will+ be executed in the empty database. If you already have tables+ created via SQL output of hledger, you would probably want to+ either clear tables of existing data (via ‘delete’ or ‘truncate’+ SQL statements) or drop tables completely as otherwise your+ postings will be duped.+++File: hledger.info, Node: Commodity styles, Next: Colour, Prev: Output format, Up: Output++6.3 Commodity styles+====================++When displaying amounts, hledger infers a standard display style for+each commodity/currency, as described below in Commodity display style.++ If needed, this can be overridden by a ‘-c/--commodity-style’ option+(except for cost amounts and amounts displayed by the ‘print’ command,+which are always displayed with all decimal digits). For example, the+following will force dollar amounts to be displayed as shown:++$ hledger print -c '$1.000,0'++ This option can repeated to set the display style for multiple+commodities/currencies. Its argument is as described in the commodity+directive.+++File: hledger.info, Node: Colour, Next: Box-drawing, Prev: Commodity styles, Up: Output++6.4 Colour+==========++In terminal output, some commands can produce colour when the terminal+supports it:++ • if the ‘--color/--colour’ option is given a value of ‘yes’ or+ ‘always’ (or ‘no’ or ‘never’), colour will (or will not) be used;+ • otherwise, if the ‘NO_COLOR’ environment variable is set, colour+ will not be used;+ • otherwise, colour will be used if the output (terminal or file)+ supports it.+++File: hledger.info, Node: Box-drawing, Next: Debug output, Prev: Colour, Up: Output++6.5 Box-drawing+===============++In terminal output, you can enable unicode box-drawing characters to+render prettier tables:++ • if the ‘--pretty’ option is given a value of ‘yes’ or ‘always’ (or+ ‘no’ or ‘never’), unicode characters will (or will not) be used;+ • otherwise, unicode characters will not be used.+++File: hledger.info, Node: Debug output, Prev: Box-drawing, Up: Output++6.6 Debug output+================++We intend hledger to be relatively easy to troubleshoot, introspect and+develop. You can add ‘--debug[=N]’ to any hledger command line to see+additional debug output. N ranges from 1 (least output, the default) to+9 (maximum output). Typically you would start with 1 and increase until+you are seeing enough. Debug output goes to stderr, and is not affected+by ‘-o/--output-file’ (unless you redirect stderr to stdout, eg:+‘2>&1’). It will be interleaved with normal output, which can help+reveal when parts of the code are evaluated. To capture debug output in+a log file instead, you can usually redirect stderr, eg:++hledger bal --debug=3 2>hledger.log+++File: hledger.info, Node: Limitations, Next: Troubleshooting, Prev: Output, Up: Top++7 Limitations+*************++The need to precede add-on command options with ‘--’ when invoked from+hledger is awkward.++ When input data contains non-ascii characters, a suitable system+locale must be configured (or there will be an unhelpful error). Eg on+POSIX, set LANG to something other than C.++ In a Microsoft Windows CMD window, non-ascii characters and colours+are not supported.++ On Windows, non-ascii characters may not display correctly when+running a hledger built in CMD in MSYS/CYGWIN, or vice-versa.++ In a Cygwin/MSYS/Mintty window, the tab key is not supported in+hledger add.++ Not all of Ledger’s journal file syntax is supported. See hledger+and Ledger > Differences > journal format.++ On large data files, hledger is slower and uses more memory than+Ledger.+++File: hledger.info, Node: Troubleshooting, Next: PART 2 DATA FORMATS, Prev: Limitations, Up: Top++8 Troubleshooting+*****************++Here are some issues you might encounter when you run hledger (and+remember you can also seek help from the IRC channel, mail list or bug+tracker):++ *Successfully installed, but "No command ’hledger’ found"*+stack and cabal install binaries into a special directory, which should+be added to your PATH environment variable. Eg on unix-like systems,+that is ~/.local/bin and ~/.cabal/bin respectively.++ *I set a custom LEDGER_FILE, but hledger is still using the default+file*+‘LEDGER_FILE’ should be a real environment variable, not just a shell+variable. The command ‘env | grep LEDGER_FILE’ should show it. You may+need to use ‘export’. Here’s an explanation.++ *Getting errors like "Illegal byte sequence" or "Invalid or+incomplete multibyte or wide character" or "commitAndReleaseBuffer:+invalid argument (invalid character)"*+Programs compiled with GHC (hledger, haskell build tools, etc.) need to+have a UTF-8-aware locale configured in the environment, otherwise they+will fail with these kinds of errors when they encounter non-ascii+characters.++ To fix it, set the LANG environment variable to some locale which+supports UTF-8. The locale you choose must be installed on your system.++ Here’s an example of setting LANG temporarily, on Ubuntu GNU/Linux:++$ file my.journal+my.journal: UTF-8 Unicode text # the file is UTF8-encoded+$ echo $LANG+C # LANG is set to the default locale, which does not support UTF8+$ locale -a # which locales are installed ?+C+en_US.utf8 # here's a UTF8-aware one we can use+POSIX+$ LANG=en_US.utf8 hledger -f my.journal print # ensure it is used for this command++ If available, ‘C.UTF-8’ will also work. If your preferred locale+isn’t listed by ‘locale -a’, you might need to install it. Eg on+Ubuntu/Debian:++$ apt-get install language-pack-fr+$ locale -a+C+en_US.utf8+fr_BE.utf8+fr_CA.utf8+fr_CH.utf8+fr_FR.utf8+fr_LU.utf8+POSIX+$ LANG=fr_FR.utf8 hledger -f my.journal print++ Here’s how you could set it permanently, if you use a bash shell:++$ echo "export LANG=en_US.utf8" >>~/.bash_profile+$ bash --login++ Exact spelling and capitalisation may be important. Note the+difference on MacOS (‘UTF-8’, not ‘utf8’). Some platforms (eg ubuntu)+allow variant spellings, but others (eg macos) require it to be exact:++$ locale -a | grep -iE en_us.*utf+en_US.UTF-8+$ LANG=en_US.UTF-8 hledger -f my.journal print+++File: hledger.info, Node: PART 2 DATA FORMATS, Next: Journal, Prev: Troubleshooting, Up: Top++9 PART 2: DATA FORMATS+**********************+++File: hledger.info, Node: Journal, Next: CSV, Prev: PART 2 DATA FORMATS, Up: Top++10 Journal+**********++hledger’s default file format, representing a General Journal. Here’s a+cheatsheet/mini-tutorial, or you can skip ahead to About journal format.++* Menu:++* Journal cheatsheet::+* About journal format::+* Comments::+* Transactions::+* Dates::+* Status::+* Code::+* Description::+* Transaction comments::+* Postings::+* Account names::+* Amounts::+* Costs::+* Balance assertions::+* Posting comments::+* Tags::+* Directives::+* account directive::+* alias directive::+* commodity directive::+* decimal-mark directive::+* include directive::+* P directive::+* payee directive::+* tag directive::+* Periodic transactions::+* Other syntax::+++File: hledger.info, Node: Journal cheatsheet, Next: About journal format, Up: Journal++10.1 Journal cheatsheet+=======================++# Here is the main syntax of hledger's journal format+# (omitting extra Ledger compatibility syntax).+# hledger journals contain comments, directives, and transactions, in any order:++###############################################################################+# 1. Comment lines are for notes or temporarily disabling things.+# They begin with #, ;, or a line containing the word "comment".++# hash comment line+; semicolon comment line+comment+These lines+are commented.+end comment++# Some but not all hledger entries can have same-line comments attached to them,+# from ; (semicolon) to end of line.++###############################################################################+# 2. Directives modify parsing or reports in some way.+# They begin with a word or letter (or symbol).++account actifs ; type:A, declare an account that is an Asset. 2+ spaces before ;.+account passifs ; type:L, declare an account that is a Liability, and so on.. (ALERX)+alias chkg = assets:checking+commodity $0.00+decimal-mark .+include /dev/null+payee Whole Foods+P 2022-01-01 AAAA $1.40+~ monthly budget goals ; <- 2+ spaces between period expression and description+ expenses:food $400+ expenses:home $1000+ budgeted++###############################################################################+# 3. Transactions are what it's all about; they are dated events,+# usually describing movements of money.+# They begin with a date.++# DATE DESCRIPTION ; This is a transaction comment.+# ACCOUNT NAME 1 AMOUNT1 ; <- posting 1. This is a posting comment.+# ACCOUNT NAME 2 AMOUNT2 ; <- posting 2. Postings must be indented.+# ; ^^ At least 2 spaces between account and amount.+# ... ; Any number of postings is allowed. The amounts must balance (sum to 0).++2022-01-01 opening balances are declared this way+ assets:checking $1000 ; Account names can be anything. lower case is easy to type.+ assets:savings $1000 ; assets, liabilities, equity, revenues, expenses are common.+ assets:cash:wallet $100 ; : indicates subaccounts.+ liabilities:credit card $-200 ; liabilities, equity, revenues balances are usually negative.+ equity ; One amount can be left blank; $-1900 is inferred here.++2022-04-15 * (#12345) pay taxes+ ; There can be a ! or * after the date meaning "pending" or "cleared".+ ; There can be a transaction code (text in parentheses) after the date/status.+ ; Amounts' sign represents direction of flow, or credit/debit:+ assets:checking $-500 ; minus means removed from this account (credit)+ expenses:tax:us:2021 $500 ; plus means added to this account (debit)+ ; revenue/expense categories are also "accounts"++Kv+2022-01-01 ; The description is optional.+ ; Any currency/commodity symbols are allowed, on either side.+ assets:cash:wallet GBP -10+ expenses:clothing GBP 10+ assets:gringotts -10 gold+ assets:pouch 10 gold+ revenues:gifts -2 "Liquorice Wands" ; Complex symbols+ assets:bag 2 "Liquorice Wands" ; must be double-quoted.++2022-01-01 Cost in another commodity can be noted with @ or @@+ assets:investments 2.0 AAAA @ $1.50 ; @ means per-unit cost+ assets:investments 3.0 AAAA @@ $4 ; @@ means total cost+ assets:checking $-7.00++2022-01-02 assert balances+ ; Balances can be asserted for extra error checking, in any transaction.+ assets:investments 0 AAAA = 5.0 AAAA+ assets:pouch 0 gold = 10 gold+ assets:savings $0 = $1000++1999-12-31 Ordering transactions by date is recommended but not required.+ ; Postings are not required.++2022.01.01 These date+2022/1/1 formats are+12/31 also allowed (but consistent YYYY-MM-DD is recommended).+++File: hledger.info, Node: About journal format, Next: Comments, Prev: Journal cheatsheet, Up: Journal++10.2 About journal format+=========================++hledger’s usual data source is a plain text file containing journal+entries in hledger journal format. This file represents a standard+accounting general journal. I use file names ending in ‘.journal’, but+that’s not required. The journal file contains a number of transaction+entries, each describing a transfer of money (or any commodity) between+two or more named accounts, in a simple format readable by both hledger+and humans.++ hledger’s journal format is a compatible subset, mostly, of ledger’s+journal format, so hledger can work with compatible ledger journal files+as well. It’s safe, and encouraged, to run both hledger and ledger on+the same journal file, eg to validate the results you’re getting.++ You can use hledger without learning any more about this file; just+use the add or web or import commands to create and update it.++ Many users, though, edit the journal file with a text editor, and+track changes with a version control system such as git. Editor addons+such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and+hledger-vscode for Visual Studio Code, make this easier, adding colour,+formatting, tab completion, and useful commands. See Editor+configuration at hledger.org for the full list.++ Here’s a description of each part of the file format (and hledger’s+data model).++ A hledger journal file can contain three kinds of thing: file+comments, transactions, and/or directives (counting periodic transaction+rules and auto posting rules as directives).+++File: hledger.info, Node: Comments, Next: Transactions, Prev: About journal format, Up: Journal++10.3 Comments+=============++Lines in the journal will be ignored if they begin with a hash (‘#’) or+a semicolon (‘;’). (See also Other syntax.) hledger will also ignore+regions beginning with a ‘comment’ line and ending with an ‘end comment’+line (or file end). Here’s a suggestion for choosing between them:++ • ‘#’ for top-level notes+ • ‘;’ for commenting out things temporarily+ • ‘comment’ for quickly commenting large regions (remember it’s+ there, or you might get confused)++ Eg:++# a comment line+; another commentline+comment+A multi-line comment block,+continuing until "end comment" directive+or the end of the current file.+end comment++ Some hledger entries can have same-line comments attached to them,+from ; (semicolon) to end of line. See Transaction comments, Posting+comments, and Account comments below.+++File: hledger.info, Node: Transactions, Next: Dates, Prev: Comments, Up: Journal++10.4 Transactions+=================++Transactions are the main unit of information in a journal file. They+represent events, typically a movement of some quantity of commodities+between two or more named accounts.++ Each transaction is recorded as a journal entry, beginning with a+simple date in column 0. This can be followed by any of the following+optional fields, separated by spaces:++ • a status character (empty, ‘!’, or ‘*’)+ • a code (any short number or text, enclosed in parentheses)+ • a description (any remaining text until end of line or a semicolon)+ • a comment (any remaining text following a semicolon until end of+ line, and any following indented lines beginning with a semicolon)+ • 0 or more indented _posting_ lines, describing what was transferred+ and the accounts involved (indented comment lines are also allowed,+ but not blank lines or non-indented lines).++ Here’s a simple journal file containing one transaction:++2008/01/01 income+ assets:bank:checking $1+ income:salary $-1+++File: hledger.info, Node: Dates, Next: Status, Prev: Transactions, Up: Journal++10.5 Dates+==========++* Menu:++* Simple dates::+* Posting dates::+++File: hledger.info, Node: Simple dates, Next: Posting dates, Up: Dates++10.5.1 Simple dates+-------------------++Dates in the journal file use _simple dates_ format: ‘YYYY-MM-DD’ or+‘YYYY/MM/DD’ or ‘YYYY.MM.DD’, with leading zeros optional. The year may+be omitted, in which case it will be inferred from the context: the+current transaction, the default year set with a ‘Y’ directive, or the+current date when the command is run. Some examples: ‘2010-01-31’,+‘2010/01/31’, ‘2010.1.31’, ‘1/31’.++ (The UI also accepts simple dates, as well as the more flexible smart+dates documented in the hledger manual.)+++File: hledger.info, Node: Posting dates, Prev: Simple dates, Up: Dates++10.5.2 Posting dates+--------------------++You can give individual postings a different date from their parent+transaction, by adding a posting comment containing a tag (see below)+like ‘date:DATE’. This is probably the best way to control posting+dates precisely. Eg in this example the expense should appear in May+reports, and the deduction from checking should be reported on 6/1 for+easy bank reconciliation:++2015/5/30+ expenses:food $10 ; food purchased on saturday 5/30+ assets:checking ; bank cleared it on monday, date:6/1++$ hledger -f t.j register food+2015-05-30 expenses:food $10 $10++$ hledger -f t.j register checking+2015-06-01 assets:checking $-10 $-10++ DATE should be a simple date; if the year is not specified it will+use the year of the transaction’s date.+The ‘date:’ tag must have a valid simple date value if it is present, eg+a ‘date:’ tag with no value is not allowed.+++File: hledger.info, Node: Status, Next: Code, Prev: Dates, Up: Journal++10.6 Status+===========++Transactions, or individual postings within a transaction, can have a+status mark, which is a single character before the transaction+description or posting account name, separated from it by a space,+indicating one of three statuses:++mark status+ +-----------------+ unmarked+‘!’ pending+‘*’ cleared++ When reporting, you can filter by status with the ‘-U/--unmarked’,+‘-P/--pending’, and ‘-C/--cleared’ flags; or the ‘status:’, ‘status:!’,+and ‘status:*’ queries; or the U, P, C keys in hledger-ui.++ Note, in Ledger and in older versions of hledger, the "unmarked"+state is called "uncleared". As of hledger 1.3 we have renamed it to+unmarked for clarity.++ To replicate Ledger and old hledger’s behaviour of also matching+pending, combine -U and -P.++ Status marks are optional, but can be helpful eg for reconciling with+real-world accounts. Some editor modes provide highlighting and+shortcuts for working with status. Eg in Emacs ledger-mode, you can+toggle transaction status with C-c C-e, or posting status with C-c C-c.++ What "uncleared", "pending", and "cleared" actually mean is up to+you. Here’s one suggestion:++status meaning+--------------------------------------------------------------------------+uncleared recorded but not yet reconciled; needs review+pending tentatively reconciled (if needed, eg during a big+ reconciliation)+cleared complete, reconciled as far as possible, and considered+ correct++ With this scheme, you would use ‘-PC’ to see the current balance at+your bank, ‘-U’ to see things which will probably hit your bank soon+(like uncashed checks), and no flags to see the most up-to-date state of+your finances.+++File: hledger.info, Node: Code, Next: Description, Prev: Status, Up: Journal++10.7 Code+=========++After the status mark, but before the description, you can optionally+write a transaction "code", enclosed in parentheses. This is a good+place to record a check number, or some other important transaction id+or reference number.+++File: hledger.info, Node: Description, Next: Transaction comments, Prev: Code, Up: Journal++10.8 Description+================++A transaction’s description is the rest of the line following the date+and status mark (or until a comment begins). Sometimes called the+"narration" in traditional bookkeeping, it can be used for whatever you+wish, or left blank. Transaction descriptions can be queried, unlike+comments.++* Menu:++* Payee and note::+++File: hledger.info, Node: Payee and note, Up: Description++10.8.1 Payee and note+---------------------++You can optionally include a ‘|’ (pipe) character in descriptions to+subdivide the description into separate fields for payee/payer name on+the left (up to the first ‘|’) and an additional note field on the right+(after the first ‘|’). This may be worthwhile if you need to do more+precise querying and pivoting by payee or by note.+++File: hledger.info, Node: Transaction comments, Next: Postings, Prev: Description, Up: Journal++10.9 Transaction comments+=========================++Text following ‘;’, after a transaction description, and/or on indented+lines immediately below it, form comments for that transaction. They+are reproduced by ‘print’ but otherwise ignored, except they may contain+tags, which are not ignored.++2012-01-01 something ; a transaction comment+ ; a second line of transaction comment+ expenses 1+ assets+++File: hledger.info, Node: Postings, Next: Account names, Prev: Transaction comments, Up: Journal++10.10 Postings+==============++A posting is an addition of some amount to, or removal of some amount+from, an account. Each posting line begins with at least one space or+tab (2 or 4 spaces is common), followed by:++ • (optional) a status character (empty, ‘!’, or ‘*’), followed by a+ space+ • (required) an account name (any text, optionally containing *single+ spaces*, until end of line or a double space)+ • (optional) *two or more spaces* or tabs followed by an amount.++ Positive amounts are being added to the account, negative amounts are+being removed.++ The amounts within a transaction must always sum up to zero. As a+convenience, one amount may be left blank; it will be inferred so as to+balance the transaction.++ Be sure to note the unusual two-space delimiter between account name+and amount. This makes it easy to write account names containing+spaces. But if you accidentally leave only one space (or tab) before+the amount, the amount will be considered part of the account name.+++File: hledger.info, Node: Account names, Next: Amounts, Prev: Postings, Up: Journal++10.11 Account names+===================++Accounts are the main way of categorising things in hledger. As in+Double Entry Bookkeeping, they can represent real world accounts (such+as a bank account), or more abstract categories such as "money borrowed+from Frank" or "money spent on electricity".++ You can use any account names you like, but we usually start with the+traditional accounting categories, which in english are ‘assets’,+‘liabilities’, ‘equity’, ‘revenues’, ‘expenses’. (You might see these+referred to as A, L, E, R, X for short.)++ For more precise reporting, we usually divide the top level accounts+into more detailed subaccounts, by writing a full colon between account+name parts. For example, from the account names ‘assets:bank:checking’+and ‘expenses:food’, hledger will infer this hierarchy of five accounts:++assets+assets:bank+assets:bank:checking+expenses+expenses:food++ Shown as an outline, the hierarchical tree structure is more clear:++assets+ bank+ checking+expenses+ food++ hledger reports can summarise the account tree to any depth, so you+can go as deep as you like with subcategories, but keeping your account+names relatively simple may be best when starting out.++ Account names may be capitalised or not; they may contain letters,+numbers, symbols, or single spaces. Note, when an account name and an+amount are written on the same line, they must be separated by *two or+more spaces* (or tabs).++ Parentheses or brackets enclosing the full account name indicate+virtual postings, described below. Parentheses or brackets internal to+the account name have no special meaning.++ Account names can be altered temporarily or permanently by account+aliases.+++File: hledger.info, Node: Amounts, Next: Costs, Prev: Account names, Up: Journal++10.12 Amounts+=============++After the account name, there is usually an amount. (Important: between+account name and amount, there must be *two or more spaces*.)++ hledger’s amount format is flexible, supporting several international+formats. Here are some examples. Amounts have a number (the+"quantity"):++1++ ..and usually a currency symbol or commodity name (more on this+below), to the left or right of the quantity, with or without a+separating space:++$1+4000 AAPL+3 "green apples"++ Amounts can be preceded by a minus sign (or a plus sign, though plus+is the default), The sign can be written before or after a left-side+commodity symbol:++-$1+$-1++ One or more spaces between the sign and the number are acceptable+when parsing (but they won’t be displayed in output):+++ $1+$- 1++ Scientific E notation is allowed:++1E-6+EUR 1E3++* Menu:++* Decimal marks digit group marks::+* Commodity::+* Directives influencing number parsing and display::+* Commodity display style::+* Rounding::+++File: hledger.info, Node: Decimal marks digit group marks, Next: Commodity, Up: Amounts++10.12.1 Decimal marks, digit group marks+----------------------------------------++A _decimal mark_ can be written as a period or a comma:++1.23+1,23456780000009++ In the integer part of the quantity (left of the decimal mark),+groups of digits can optionally be separated by a _digit group mark_ - a+space, comma, or period (different from the decimal mark):++ $1,000,000.00+ EUR 2.000.000,00+INR 9,99,99,999.00+ 1 000 000.9455++ Note, a number containing a single digit group mark and no decimal+mark is ambiguous. Are these digit group marks or decimal marks ?++1,000+1.000++ If you don’t tell it otherwise, hledger will assume both of the above+are decimal marks, parsing both numbers as 1.++ To prevent confusing parsing mistakes and undetected typos,+especially if your data contains digit group marks (eg, thousands+separators), we recommend explicitly declaring the decimal mark+character in each journal file, using a directive at the top of the+file. The ‘decimal-mark’ directive is best, otherwise ‘commodity’+directives will also work. These are described below.+++File: hledger.info, Node: Commodity, Next: Directives influencing number parsing and display, Prev: Decimal marks digit group marks, Up: Amounts++10.12.2 Commodity+-----------------++Amounts in hledger have both a "quantity", which is a signed decimal+number, and a "commodity", which is a currency symbol, stock ticker, or+any word or phrase describing something you are tracking.++ If the commodity name contains non-letters (spaces, numbers, or+punctuation), you must always write it inside double quotes (‘"green+apples"’, ‘"ABC123"’).++ If you write just a bare number, that too will have a commodity, with+name ‘""’; we call that the "no-symbol commodity".++ Actually, hledger combines these single-commodity amounts into more+powerful multi-commodity amounts, which are what it works with most of+the time. A multi-commodity amount could be, eg: ‘1 USD, 2 EUR, 3.456+TSLA’. In practice, you will only see multi-commodity amounts in+hledger’s output; you can’t write them directly in the journal file.++ (If you are writing scripts or working with hledger’s internals,+these are the ‘Amount’ and ‘MixedAmount’ types.)+++File: hledger.info, Node: Directives influencing number parsing and display, Next: Commodity display style, Prev: Commodity, Up: Amounts++10.12.3 Directives influencing number parsing and display+---------------------------------------------------------++You can add ‘decimal-mark’ and ‘commodity’ directives to the journal, to+declare and control these things more explicitly and precisely. These+are described below, but here’s a quick example:++# the decimal mark character used by all amounts in this file (all commodities)+decimal-mark .++# display styles for the $, EUR, INR and no-symbol commodities:+commodity $1,000.00+commodity EUR 1.000,00+commodity INR 9,99,99,999.00+commodity 1 000 000.9455+++File: hledger.info, Node: Commodity display style, Next: Rounding, Prev: Directives influencing number parsing and display, Up: Amounts++10.12.4 Commodity display style+-------------------------------++For the amounts in each commodity, hledger chooses a consistent display+style to use in most reports. (Exceptions: price amounts, and all+amounts displayed by the ‘print’ command, are displayed with all of+their decimal digits visible.)++ A commodity’s display style is inferred as follows.++ First, if a default commodity is declared with ‘D’, this commodity+and its style is applied to any no-symbol amounts in the journal.++ Then each commodity’s style is inferred from one of the following, in+order of preference:++ • The commodity directive for that commodity (including the no-symbol+ commodity), if any.+ • The amounts in that commodity seen in the journal’s transactions.+ (Posting amounts only; prices and periodic or auto rules are+ ignored, currently.)+ • The built-in fallback style, which looks like this: ‘$1000.00’.+ (Symbol on the left, period decimal mark, two decimal places.)++ A style is inferred from journal amounts as follows:++ • Use the general style (decimal mark, symbol placement) of the first+ amount+ • Use the first-seen digit group style (digit group mark, digit group+ sizes), if any+ • Use the maximum number of decimal places of all.++ Cost amounts don’t affect the commodity display style directly, but+occasionally they can do so indirectly (eg when a posting’s amount is+inferred using a cost). If you find this causing problems, use a+commodity directive to fix the display style.++ To summarise: each commodity’s amounts will be normalised to (a) the+style declared by a ‘commodity’ directive, or (b) the style of the first+posting amount in the journal, with the first-seen digit group style and+the maximum-seen number of decimal places. So if your reports are+showing amounts in a way you don’t like, eg with too many decimal+places, use a commodity directive. Some examples:++# declare euro, dollar, bitcoin and no-symbol commodities and set their +# input number formats and output display styles:+commodity EUR 1.000,+commodity $1000.00+commodity 1000.00000000 BTC+commodity 1 000.++ The inferred commodity style can be overridden by supplying a command+line option.+++File: hledger.info, Node: Rounding, Prev: Commodity display style, Up: Amounts++10.12.5 Rounding+----------------++Amounts are stored internally as decimal numbers with up to 255 decimal+places, and displayed with the number of decimal places specified by the+commodity display style. Note, hledger uses banker’s rounding: it+rounds to the nearest even number, eg 0.5 displayed with zero decimal+places is "0").+++File: hledger.info, Node: Costs, Next: Balance assertions, Prev: Amounts, Up: Journal++10.13 Costs+===========++After a posting amount, you can note its cost (when buying) or selling+price (when selling) in another commodity, by writing either ‘@+UNITPRICE’ or ‘@@ TOTALPRICE’ after it. This indicates a conversion+transaction, where one commodity is exchanged for another.++ (You might also see this called "transaction price" in hledger docs,+discussions, or code; that term was directionally neutral and reminded+that it is a price specific to a transaction, but we now just call it+"cost", with the understanding that the transaction could be a purchase+or a sale.)++ Costs are usually written explicitly with ‘@’ or ‘@@’, but can also+be inferred automatically for simple multi-commodity transactions.+Note, if costs are inferred, the order of postings is significant; the+first posting will have a cost attached, in the commodity of the second.++ As an example, here are several ways to record purchases of a foreign+currency in hledger, using the cost notation either explicitly or+implicitly:++ 1. Write the price per unit, as ‘@ UNITPRICE’ after the amount:++ 2009/1/1+ assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each+ assets:dollars ; balancing amount is -$135.00++ 2. Write the total price, as ‘@@ TOTALPRICE’ after the amount:++ 2009/1/1+ assets:euros €100 @@ $135 ; one hundred euros purchased at $135 for the lot+ assets:dollars++ 3. Specify amounts for all postings, using exactly two commodities,+ and let hledger infer the price that balances the transaction.+ Note the effect of posting order: the price is added to first+ posting, making it ‘€100 @@ $135’, as in example 2:++ 2009/1/1+ assets:euros €100 ; one hundred euros purchased+ assets:dollars $-135 ; for $135++ Amounts can be converted to cost at report time using the ‘-B/--cost’+flag; this is discussed more in the ˜COST REPORTING section.++* Menu:++* Other cost/lot notations::+++File: hledger.info, Node: Other cost/lot notations, Up: Costs++10.13.1 Other cost/lot notations+--------------------------------++A slight digression for Ledger and Beancount users. Ledger has a number+of cost/lot-related notations:++ • ‘@ UNITCOST’ and ‘@@ TOTALCOST’+ • expresses a conversion rate, as in hledger+ • when buying, also creates a lot than can be selected at+ selling time++ • ‘(@) UNITCOST’ and ‘(@@) TOTALCOST’ (virtual cost)+ • like the above, but also means "this cost was exceptional,+ don’t use it when inferring market prices".++ Currently, hledger treats the above like ‘@’ and ‘@@’; the+parentheses are ignored.++ • ‘{=FIXEDUNITCOST}’ and ‘{{=FIXEDTOTALCOST}}’ (fixed price)+ • when buying, means "this cost is also the fixed price, don’t+ let it fluctuate in value reports"++ • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’ (lot price)+ • can be used identically to ‘@ UNITCOST’ and ‘@@ TOTALCOST’,+ also creates a lot+ • when selling, combined with ‘@ ...’, specifies an investment+ lot by its cost basis; does not check if that lot is present++ • and related: ‘[YYYY/MM/DD]’ (lot date)+ • when buying, attaches this acquisition date to the lot+ • when selling, selects a lot by its acquisition date++ • ‘(SOME TEXT)’ (lot note)+ • when buying, attaches this note to the lot+ • when selling, selects a lot by its note++ Currently, hledger accepts any or all of the above in any order after+the posting amount, but ignores them. (This can break transaction+balancing.)++ For Beancount users, the notation and behaviour is different:++ • ‘@ UNITCOST’ and ‘@@ TOTALCOST’+ • expresses a cost without creating a lot, as in hledger+ • when buying (augmenting) or selling (reducing) a lot, combined+ with ‘{...}’: documents the cost/selling price (not used for+ transaction balancing)++ • ‘{UNITCOST}’ and ‘{{TOTALCOST}}’+ • when buying (augmenting), expresses the cost for transaction+ balancing, and also creates a lot with this cost basis+ attached+ • when selling (reducing),+ • selects a lot by its cost basis+ • raises an error if that lot is not present or can not be+ selected unambiguously (depending on booking method+ configured)+ • expresses the selling price for transaction balancing++ Currently, hledger accepts the ‘{UNITCOST}’/‘{{TOTALCOST}}’ notation+but ignores it.++ • variations: ‘{}’, ‘{YYYY-MM-DD}’, ‘{"LABEL"}’, ‘{UNITCOST,+ "LABEL"}’, ‘{UNITCOST, YYYY-MM-DD, "LABEL"}’ etc.++ Currently, hledger rejects these.+++File: hledger.info, Node: Balance assertions, Next: Posting comments, Prev: Costs, Up: Journal++10.14 Balance assertions+========================++hledger supports Ledger-style balance assertions in journal files.+These look like, for example, ‘= EXPECTEDBALANCE’ following a posting’s+amount. Eg here we assert the expected dollar balance in accounts a and+b after each posting:++2013/1/1+ a $1 =$1+ b =$-1++2013/1/2+ a $1 =$2+ b $-1 =$-2++ After reading a journal file, hledger will check all balance+assertions and report an error if any of them fail. Balance assertions+can protect you from, eg, inadvertently disrupting reconciled balances+while cleaning up old entries. You can disable them temporarily with+the ‘-I/--ignore-assertions’ flag, which can be useful for+troubleshooting or for reading Ledger files. (Note: this flag currently+does not disable balance assignments, described below).++* Menu:++* Assertions and ordering::+* Assertions and multiple included files::+* Assertions and multiple -f files::+* Assertions and commodities::+* Assertions and prices::+* Assertions and subaccounts::+* Assertions and virtual postings::+* Assertions and auto postings::+* Assertions and precision::+++File: hledger.info, Node: Assertions and ordering, Next: Assertions and multiple included files, Up: Balance assertions++10.14.1 Assertions and ordering+-------------------------------++hledger sorts an account’s postings and assertions first by date and+then (for postings on the same day) by parse order. Note this is+different from Ledger, which sorts assertions only by parse order.+(Also, Ledger assertions do not see the accumulated effect of repeated+postings to the same account within a transaction.)++ So, hledger balance assertions keep working if you reorder+differently-dated transactions within the journal. But if you reorder+same-dated transactions or postings, assertions might break and require+updating. This order dependence does bring an advantage: precise+control over the order of postings and assertions within a day, so you+can assert intra-day balances.+++File: hledger.info, Node: Assertions and multiple included files, Next: Assertions and multiple -f files, Prev: Assertions and ordering, Up: Balance assertions++10.14.2 Assertions and multiple included files+----------------------------------------------++Multiple files included with the ‘include’ directive are processed as if+concatenated into one file, preserving their order and the posting order+within each file. It means that balance assertions in later files will+see balance from earlier files.++ And if you have multiple postings to an account on the same day,+split across multiple files, and you want to assert the account’s+balance on that day, you’ll need to put the assertion in the right file+- the last one in the sequence, probably.+++File: hledger.info, Node: Assertions and multiple -f files, Next: Assertions and commodities, Prev: Assertions and multiple included files, Up: Balance assertions++10.14.3 Assertions and multiple -f files+----------------------------------------++Unlike ‘include’, when multiple files are specified on the command line+with multiple ‘-f/--file’ options, balance assertions will not see+balance from earlier files. This can be useful when you do not want+problems in earlier files to disrupt valid assertions in later files.++ If you do want assertions to see balance from earlier files, use+‘include’, or concatenate the files temporarily.+++File: hledger.info, Node: Assertions and commodities, Next: Assertions and prices, Prev: Assertions and multiple -f files, Up: Balance assertions++10.14.4 Assertions and commodities+----------------------------------++The asserted balance must be a simple single-commodity amount, and in+fact the assertion checks only this commodity’s balance within the+(possibly multi-commodity) account balance. This is how assertions work+in Ledger also. We could call this a "partial" balance assertion.++ To assert the balance of more than one commodity in an account, you+can write multiple postings, each asserting one commodity’s balance.++ You can make a stronger "total" balance assertion by writing a double+equals sign (‘== EXPECTEDBALANCE’). This asserts that there are no+other commodities in the account besides the asserted one (or at least,+that their balance is 0).++2013/1/1+ a $1+ a 1€+ b $-1+ c -1€++2013/1/2 ; These assertions succeed+ a 0 = $1+ a 0 = 1€+ b 0 == $-1+ c 0 == -1€++2013/1/3 ; This assertion fails as 'a' also contains 1€+ a 0 == $1++ It’s not yet possible to make a complete assertion about a balance+that has multiple commodities. One workaround is to isolate each+commodity into its own subaccount:++2013/1/1+ a:usd $1+ a:euro 1€+ b++2013/1/2+ a 0 == 0+ a:usd 0 == $1+ a:euro 0 == 1€+++File: hledger.info, Node: Assertions and prices, Next: Assertions and subaccounts, Prev: Assertions and commodities, Up: Balance assertions++10.14.5 Assertions and prices+-----------------------------++Balance assertions ignore costs, and should normally be written without+one:++2019/1/1+ (a) $1 @ €1 = $1++ We do allow prices to be written there, however, and print shows+them, even though they don’t affect whether the assertion passes or+fails. This is for backward compatibility (hledger’s close command used+to generate balance assertions with prices), and because balance+_assignments_ do use them (see below).+++File: hledger.info, Node: Assertions and subaccounts, Next: Assertions and virtual postings, Prev: Assertions and prices, Up: Balance assertions++10.14.6 Assertions and subaccounts+----------------------------------++The balance assertions above (‘=’ and ‘==’) do not count the balance+from subaccounts; they check the account’s exclusive balance only. You+can assert the balance including subaccounts by writing ‘=*’ or ‘==*’,+eg:++2019/1/1+ equity:opening balances+ checking:a 5+ checking:b 5+ checking 1 ==* 11+++File: hledger.info, Node: Assertions and virtual postings, Next: Assertions and auto postings, Prev: Assertions and subaccounts, Up: Balance assertions++10.14.7 Assertions and virtual postings+---------------------------------------++Balance assertions always consider both real and virtual postings; they+are not affected by the ‘--real/-R’ flag or ‘real:’ query.+++File: hledger.info, Node: Assertions and auto postings, Next: Assertions and precision, Prev: Assertions and virtual postings, Up: Balance assertions++10.14.8 Assertions and auto postings+------------------------------------++Balance assertions _are_ affected by the ‘--auto’ flag, which generates+auto postings, which can alter account balances. Because auto postings+are optional in hledger, accounts affected by them effectively have two+balances. But balance assertions can only test one or the other of+these. So to avoid making fragile assertions, either:++ • assert the balance calculated with ‘--auto’, and always use+ ‘--auto’ with that file+ • or assert the balance calculated without ‘--auto’, and never use+ ‘--auto’ with that file+ • or avoid balance assertions on accounts affected by auto postings+ (or avoid auto postings entirely).+++File: hledger.info, Node: Assertions and precision, Prev: Assertions and auto postings, Up: Balance assertions++10.14.9 Assertions and precision+--------------------------------++Balance assertions compare the exactly calculated amounts, which are not+always what is shown by reports. Eg a commodity directive may limit the+display precision, but this will not affect balance assertions. Balance+assertion failure messages show exact amounts.+++File: hledger.info, Node: Posting comments, Next: Tags, Prev: Balance assertions, Up: Journal++10.15 Posting comments+======================++Text following ‘;’, at the end of a posting line, and/or on indented+lines immediately below it, form comments for that posting. They are+reproduced by ‘print’ but otherwise ignored, except they may contain+tags, which are not ignored.++2012-01-01+ expenses 1 ; a comment for posting 1+ assets+ ; a comment for posting 2+ ; a second comment line for posting 2+++File: hledger.info, Node: Tags, Next: Directives, Prev: Posting comments, Up: Journal++10.16 Tags+==========++Tags are a way to add extra labels or labelled data to transactions,+postings, or accounts, which you can then search or pivot on.++ They are written as a word (optionally hyphenated) immediately+followed by a full colon, in a transaction or posting or account+directive’s comment. (This is an exception to the usual rule that+things in comments are ignored.) Eg, here four different tags are+recorded: one on the checking account, two on the transaction, and one+on the expenses posting:++account assets:checking ; accounttag:++2017/1/16 bought groceries ; transactiontag-1:+ ; transactiontag-2:+ assets:checking $-1+ expenses:food $1 ; postingtag:++ Postings also inherit tags from their transaction and their account.+And transactions also acquire tags from their postings (and postings’+accounts). So in the example above, the expenses posting effectively+has all four tags (by inheriting from account and transaction), and the+transaction also has all four tags (by acquiring from the expenses+posting).++ You can list tag names with ‘hledger tags [NAMEREGEX]’, or match by+tag name with a ‘tag:NAMEREGEX’ query.++* Menu:++* Tag values::+++File: hledger.info, Node: Tag values, Up: Tags++10.16.1 Tag values+------------------++Tags can have a value, which is any text after the colon up until a+comma or end of line (with surrounding whitespace removed). Note this+means that hledger tag values can not contain commas. Eg in the+following posting, the three tags’ values are "value 1", "value 2", and+"" (empty) respectively:++ expenses:food $10 ; foo, tag1: value 1 , tag2:value 2, bar tag3: , baz++ Note that tags can be repeated, and are additive rather than+overriding: when the same tag name is seen again with a new value, the+new name:value pair is added to the tags. (It is not possible to+override a tag’s value or remove a tag.)++ You can list a tag’s values with ‘hledger tags TAGNAME --values’, or+match by tag value with a ‘tag:NAMEREGEX=VALUEREGEX’ query.+++File: hledger.info, Node: Directives, Next: account directive, Prev: Tags, Up: Journal++10.17 Directives+================++A directive is a line in the journal beginning with a special keyword,+that influences how the journal is processed, how things are displayed,+and so on. hledger’s directives are based on (a subset of) Ledger’s,+but there are many differences, and also some differences between+hledger versions. Here are some more definitions:++ • _subdirective_ - Some directives support subdirectives, written+ indented below the parent directive.++ • _decimal mark_ - The character to interpret as a decimal mark+ (period or comma) when parsing amounts of a commodity.++ • _display style_ - How to display amounts of a commodity in output:+ symbol side and spacing, digit groups, decimal mark, and number of+ decimal places.++ Directives are not required when starting out with hledger, but you+will probably want to add some as your needs grow. Here some key+directives for particular needs:++purpose directives+--------------------------------------------------------------------------+*READING DATA:*+Declare file’s decimal mark to help parse ‘decimal-mark’+amounts accurately+Rewrite account names ‘alias’+Comment out sections of the data ‘comment’+Include extra data files ‘include’+*GENERATING DATA:*+Generate recurring transactions or budget ‘~’+goals+Generate extra postings on transactions ‘=’+*CHECKING FOR ERRORS:*+Define valid entities to provide more ‘account’, ‘commodity’,+error checking ‘payee’+*REPORTING:*+Declare accounts’ type and display order ‘account’+Declare commodity display styles ‘commodity’+Declare market prices ‘P’++* Menu:++* Directive effects::+* Directives and multiple files::+++File: hledger.info, Node: Directive effects, Next: Directives and multiple files, Up: Directives++10.17.1 Directive effects+-------------------------++And here is what each directive does, and which files and journal+entries (transactions) it affects:++directivewhat it does ends+ at+ file+ end?+---------------------------------------------------------------------------+*‘account’*Declares an account, for checking all entries in all files; andN+ its display order and type. Subdirectives: any text, ignored.+*‘alias’*Rewrites account names, in following entries until end of Y+ current file or ‘end aliases’. Command line equivalent:+ ‘--alias’+*‘comment’*Ignores part of the journal file, until end of current file orY+ ‘end comment’.+*‘commodity’*Declares up to four things: 1. a commodity symbol, for checkingN,Y,N,N+ all amounts in all files 2. the decimal mark for parsing+ amounts of this commodity, in the following entries until end of+ current file (if there is no ‘decimal-mark’ directive) 3. and+ the display style for amounts of this commodity 4. which is+ also the precision to use for balanced-transaction checking in+ this commodity. Takes precedence over ‘D’. Subdirectives:+ ‘format’ (Ledger-compatible syntax). Command line equivalent:+ ‘-c/--commodity-style’+*‘decimal-mark’*Declares the decimal mark, for parsing amounts of all Y+ commodities in following entries until next ‘decimal-mark’ or+ end of current file. Included files can override. Takes+ precedence over ‘commodity’ and ‘D’.+*‘include’*Includes entries and directives from another file, as if theyN+ were written inline. Command line alternative: multiple+ ‘-f/--file’+*‘payee’*Declares a payee name, for checking all entries in all files. N+*‘P’*Declares the market price of a commodity on some date, for value N+ reports.+*‘~’*Declares a periodic transaction rule that generates future N+(tilde)transactions with ‘--forecast’ and budget goals with ‘balance+ --budget’.+Other+syntax:+*‘applyPrepends a common parent account to all account names, in Y+account’*following entries until end of current file or ‘end apply+ account’.+*‘D’*Sets a default commodity to use for no-symbol amounts;and, if Y,Y,N,N+ there is no ‘commodity’ directive for this commodity: its+ decimal mark, balancing precision, and display style, as above.+*‘Y’*Sets a default year to use for any yearless dates, in following Y+ entries until end of current file.+*‘=’*Declares an auto posting rule that generates extra postings on partly+(equals)matched transactions with ‘--auto’, in current, parent, and+ child files (but not sibling files, see #1212).+*OtherOther directives from Ledger’s file format are accepted but+Ledgerignored.+directives*+++File: hledger.info, Node: Directives and multiple files, Prev: Directive effects, Up: Directives++10.17.2 Directives and multiple files+-------------------------------------++If you use multiple ‘-f’/‘--file’ options, or the ‘include’ directive,+hledger will process multiple input files. But directives which affect+input typically have effect only until the end of the file in which they+occur (and on any included files in that region).++ This may seem inconvenient, but it’s intentional; it makes reports+stable and deterministic, independent of the order of input. Otherwise+you could see different numbers if you happened to write -f options in a+different order, or if you moved includes around while cleaning up your+files.++ It can be surprising though; for example, it means that ‘alias’+directives do not affect parent or sibling files (see below).+++File: hledger.info, Node: account directive, Next: alias directive, Prev: Directives, Up: Journal++10.18 ‘account’ directive+=========================++‘account’ directives can be used to declare accounts (ie, the places+that amounts are transferred from and to). Though not required, these+declarations can provide several benefits:++ • They can document your intended chart of accounts, providing a+ reference.+ • In strict mode, they restrict which accounts may be posted to by+ transactions, which helps detect typos.+ • They control account display order in reports, allowing+ non-alphabetic sorting (eg Revenues to appear above Expenses).+ • They help with account name completion (in hledger add,+ hledger-web, hledger-iadd, ledger-mode, etc.)+ • They can store additional account information as comments, or as+ tags which can be used to filter or pivot reports.+ • They can help hledger know your accounts’ types (asset, liability,+ equity, revenue, expense), affecting reports like balancesheet and+ incomestatement.++ They are written as the word ‘account’ followed by a hledger-style+account name, eg:++account assets:bank:checking++ Note, however, that accounts declared in account directives are not+allowed to have surrounding brackets and parentheses, unlike accounts+used in postings. So the following journal will not parse:++account (assets:bank:checking)++* Menu:++* Account comments::+* Account subdirectives::+* Account error checking::+* Account display order::+* Account types::+++File: hledger.info, Node: Account comments, Next: Account subdirectives, Up: account directive++10.18.1 Account comments+------------------------++Text following *two or more spaces* and ‘;’ at the end of an account+directive line, and/or following ‘;’ on indented lines immediately below+it, form comments for that account. They are ignored except they may+contain tags, which are not ignored.++ The two-space requirement for same-line account comments is because+‘;’ is allowed in account names.++account assets:bank:checking ; same-line comment, at least 2 spaces before the semicolon+ ; next-line comment+ ; some tags - type:A, acctnum:12345+++File: hledger.info, Node: Account subdirectives, Next: Account error checking, Prev: Account comments, Up: account directive++10.18.2 Account subdirectives+-----------------------------++Ledger-style indented subdirectives are also accepted, but currently+ignored:++account assets:bank:checking+ format subdirective is ignored+++File: hledger.info, Node: Account error checking, Next: Account display order, Prev: Account subdirectives, Up: account directive++10.18.3 Account error checking+------------------------------++By default, accounts need not be declared; they come into existence when+a posting references them. This is convenient, but it means hledger+can’t warn you when you mis-spell an account name in the journal.+Usually you’ll find that error later, as an extra account in balance+reports, or an incorrect balance when reconciling.++ In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will+report an error if any transaction uses an account name that has not+been declared by an account directive. Some notes:++ • The declaration is case-sensitive; transactions must use the+ correct account name capitalisation.+ • The account directive’s scope is "whole file and below" (see+ directives). This means it affects all of the current file, and+ any files it includes, but not parent or sibling files. The+ position of account directives within the file does not matter,+ though it’s usual to put them at the top.+ • Accounts can only be declared in ‘journal’ files, but will affect+ included files of all types.+ • It’s currently not possible to declare "all possible subaccounts"+ with a wildcard; every account posted to must be declared.+++File: hledger.info, Node: Account display order, Next: Account types, Prev: Account error checking, Up: account directive++10.18.4 Account display order+-----------------------------++The order in which account directives are written influences the order+in which accounts appear in reports, hledger-ui, hledger-web etc. By+default accounts appear in alphabetical order, but if you add these+account directives to the journal file:++account assets+account liabilities+account equity+account revenues+account expenses++ those accounts will be displayed in declaration order:++$ hledger accounts -1+assets+liabilities+equity+revenues+expenses++ Any undeclared accounts are displayed last, in alphabetical order.++ Sorting is done at each level of the account tree, within each group+of sibling accounts under the same parent. And currently, this+directive:++account other:zoo++ would influence the position of ‘zoo’ among ‘other’’s subaccounts,+but not the position of ‘other’ among the top-level accounts. This+means:++ • you will sometimes declare parent accounts (eg ‘account other’+ above) that you don’t intend to post to, just to customize their+ display order+ • sibling accounts stay together (you couldn’t display ‘x:y’ in+ between ‘a:b’ and ‘a:c’).+++File: hledger.info, Node: Account types, Prev: Account display order, Up: account directive++10.18.5 Account types+---------------------++hledger knows that accounts come in several types: assets, liabilities,+expenses and so on. This enables easy reports like balancesheet and+incomestatement, and filtering by account type with the ‘type:’ query.++ As a convenience, hledger will detect these account types+automatically if you are using common english-language top-level account+names (described below). But generally we recommend you declare types+explicitly, by adding a ‘type:’ tag to your top-level account+directives. Subaccounts will inherit the type of their parent. The+tag’s value should be one of the five main account types:++ • ‘A’ or ‘Asset’ (things you own)+ • ‘L’ or ‘Liability’ (things you owe)+ • ‘E’ or ‘Equity’ (investment/ownership; balanced counterpart of+ assets & liabilities)+ • ‘R’ or ‘Revenue’ (what you received money from, AKA income;+ technically part of Equity)+ • ‘X’ or ‘Expense’ (what you spend money on; technically part of+ Equity)++ or, it can be (these are used less often):++ • ‘C’ or ‘Cash’ (a subtype of Asset, indicating liquid assets for the+ cashflow report)+ • ‘V’ or ‘Conversion’ (a subtype of Equity, for conversions (see COST+ REPORTING).)++ Here is a typical set of account type declarations:++account assets ; type: A+account liabilities ; type: L+account equity ; type: E+account revenues ; type: R+account expenses ; type: X++account assets:bank ; type: C+account assets:cash ; type: C++account equity:conversion ; type: V++ Here are some tips for working with account types.++ • The rules for inferring types from account names are as follows.+ These are just a convenience that sometimes help new users get+ going; if they don’t work for you, just ignore them and declare+ your account types. See also Regular expressions.++ If account's name contains this (CI) regular expression: | its type is:+ --------------------------------------------------------------------|-------------+ ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash+ ^assets?(:|$) | Asset+ ^(debts?|liabilit(y|ies))(:|$) | Liability+ ^equity:(trad(e|ing)|conversion)s?(:|$) | Conversion+ ^equity(:|$) | Equity+ ^(income|revenue)s?(:|$) | Revenue+ ^expenses?(:|$) | Expense++ • If you declare any account types, it’s a good idea to declare an+ account for all of the account types, because a mixture of declared+ and name-inferred types can disrupt certain reports.++ • Certain uses of account aliases can disrupt account types. See+ Rewriting accounts > Aliases and account types.++ • As mentioned above, subaccounts will inherit a type from their+ parent account. More precisely, an account’s type is decided by+ the first of these that exists:++ 1. A ‘type:’ declaration for this account.+ 2. A ‘type:’ declaration in the parent accounts above it,+ preferring the nearest.+ 3. An account type inferred from this account’s name.+ 4. An account type inferred from a parent account’s name,+ preferring the nearest parent.+ 5. Otherwise, it will have no type.++ • For troubleshooting, you can list accounts and their types with:++ $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]+++File: hledger.info, Node: alias directive, Next: commodity directive, Prev: account directive, Up: Journal++10.19 ‘alias’ directive+=======================++You can define account alias rules which rewrite your account names, or+parts of them, before generating reports. This can be useful for:++ • expanding shorthand account names to their full form, allowing+ easier data entry and a less verbose journal+ • adapting old journals to your current chart of accounts+ • experimenting with new account organisations, like a new hierarchy+ • combining two accounts into one, eg to see their sum or difference+ on one line+ • customising reports++ Account aliases also rewrite account names in account directives.+They do not affect account names being entered via hledger add or+hledger-web.++ Account aliases are very powerful. They are generally easy to use+correctly, but you can also generate invalid account names with them;+more on this below.++ See also Rewrite account names.++* Menu:++* Basic aliases::+* Regex aliases::+* Combining aliases::+* Aliases and multiple files::+* end aliases directive::+* Aliases can generate bad account names::+* Aliases and account types::+++File: hledger.info, Node: Basic aliases, Next: Regex aliases, Up: alias directive++10.19.1 Basic aliases+---------------------++To set an account alias, use the ‘alias’ directive in your journal file.+This affects all subsequent journal entries in the current file or its+included files (but note: not sibling or parent files). The spaces+around the = are optional:++alias OLD = NEW++ Or, you can use the ‘--alias 'OLD=NEW'’ option on the command line.+This affects all entries. It’s useful for trying out aliases+interactively.++ OLD and NEW are case sensitive full account names. hledger will+replace any occurrence of the old account name with the new one.+Subaccounts are also affected. Eg:++alias checking = assets:bank:wells fargo:checking+; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"+++File: hledger.info, Node: Regex aliases, Next: Combining aliases, Prev: Basic aliases, Up: alias directive++10.19.2 Regex aliases+---------------------++There is also a more powerful variant that uses a regular expression,+indicated by wrapping the pattern in forward slashes. (This is the only+place where hledger requires forward slashes around a regular+expression.)++ Eg:++alias /REGEX/ = REPLACEMENT++ or:++$ hledger --alias '/REGEX/=REPLACEMENT' ...++ Any part of an account name matched by REGEX will be replaced by+REPLACEMENT. REGEX is case-insensitive as usual.++ If you need to match a forward slash, escape it with a backslash, eg+‘/\/=:’.++ If REGEX contains parenthesised match groups, these can be referenced+by the usual backslash and number in REPLACEMENT:++alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3+; rewrites "assets:bank:wells fargo:checking" to "assets:wells fargo checking"++ REPLACEMENT continues to the end of line (or on command line, to end+of option argument), so it can contain trailing whitespace.+++File: hledger.info, Node: Combining aliases, Next: Aliases and multiple files, Prev: Regex aliases, Up: alias directive++10.19.3 Combining aliases+-------------------------++You can define as many aliases as you like, using journal directives+and/or command line options.++ Recursive aliases - where an account name is rewritten by one alias,+then by another alias, and so on - are allowed. Each alias sees the+effect of previously applied aliases.++ In such cases it can be important to understand which aliases will be+applied and in which order. For (each account name in) each journal+entry, we apply:++ 1. ‘alias’ directives preceding the journal entry, most recently+ parsed first (ie, reading upward from the journal entry, bottom to+ top)+ 2. ‘--alias’ options, in the order they appeared on the command line+ (left to right).++ In other words, for (an account name in) a given journal entry:++ • the nearest alias declaration before/above the entry is applied+ first+ • the next alias before/above that will be be applied next, and so on+ • aliases defined after/below the entry do not affect it.++ This gives nearby aliases precedence over distant ones, and helps+provide semantic stability - aliases will keep working the same way+independent of which files are being read and in which order.++ In case of trouble, adding ‘--debug=6’ to the command line will show+which aliases are being applied when.+++File: hledger.info, Node: Aliases and multiple files, Next: end aliases directive, Prev: Combining aliases, Up: alias directive++10.19.4 Aliases and multiple files+----------------------------------++As explained at Directives and multiple files, ‘alias’ directives do not+affect parent or sibling files. Eg in this command,++hledger -f a.aliases -f b.journal++ account aliases defined in a.aliases will not affect b.journal.+Including the aliases doesn’t work either:++include a.aliases++2020-01-01 ; not affected by a.aliases+ foo 1+ bar++ This means that account aliases should usually be declared at the+start of your top-most file, like this:++alias foo=Foo+alias bar=Bar++2020-01-01 ; affected by aliases above+ foo 1+ bar++include c.journal ; also affected+++File: hledger.info, Node: end aliases directive, Next: Aliases can generate bad account names, Prev: Aliases and multiple files, Up: alias directive++10.19.5 ‘end aliases’ directive+-------------------------------++You can clear (forget) all currently defined aliases (seen in the+journal so far, or defined on the command line) with this directive:++end aliases+++File: hledger.info, Node: Aliases can generate bad account names, Next: Aliases and account types, Prev: end aliases directive, Up: alias directive++10.19.6 Aliases can generate bad account names+----------------------------------------------++Be aware that account aliases can produce malformed account names, which+could cause confusing reports or invalid ‘print’ output. For example,+you could erase all account names:++2021-01-01+ a:aa 1+ b++$ hledger print --alias '/.*/='+2021-01-01+ 1++ The above ‘print’ output is not a valid journal. Or you could insert+an illegal double space, causing ‘print’ output that would give a+different journal when reparsed:++2021-01-01+ old 1+ other++$ hledger print --alias old="new USD" | hledger -f- print+2021-01-01+ new USD 1+ other+++File: hledger.info, Node: Aliases and account types, Prev: Aliases can generate bad account names, Up: alias directive++10.19.7 Aliases and account types+---------------------------------++If an account with a type declaration (see Declaring accounts > Account+types) is renamed by an alias, normally the account type remains in+effect.++ However, renaming in a way that reshapes the account tree (eg+renaming parent accounts but not their children, or vice versa) could+prevent child accounts from inheriting the account type of their+parents.++ Secondly, if an account’s type is being inferred from its name,+renaming it by an alias could prevent or alter that.++ If you are using account aliases and the ‘type:’ query is not+matching accounts as you expect, try troubleshooting with the accounts+command, eg something like:++$ hledger accounts --alias assets=bassetts type:a+++File: hledger.info, Node: commodity directive, Next: decimal-mark directive, Prev: alias directive, Up: Journal++10.20 ‘commodity’ directive+===========================++You can use ‘commodity’ directives to declare your commodities. In fact+the ‘commodity’ directive performs several functions at once:++ 1. It declares commodities which may be used in the journal. This can+ optionally be enforced, providing useful error checking. (Cf+ Commodity error checking)++ 2. It declares which decimal mark character (period or comma), to+ expect when parsing input - useful to disambiguate international+ number formats in your data. Without this, hledger will parse both+ ‘1,000’ and ‘1.000’ as 1. (Cf Amounts)++ 3. It declares how to render the commodity’s amounts when displaying+ output - the decimal mark, any digit group marks, the number of+ decimal places, symbol placement and so on. (Cf Commodity display+ style)++ You will run into one of the problems solved by commodity directives+sooner or later, so we recommend using them, for robust and predictable+parsing and display.++ Generally you should put them at the top of your journal file (since+for function 2, they affect only following amounts, cf #793).++ A commodity directive is just the word ‘commodity’ followed by a+sample amount, like this:++;commodity SAMPLEAMOUNT++commodity $1000.00+commodity 1,000.0000 AAAA ; optional same-line comment++ It may also be written on multiple lines, and use the ‘format’+subdirective, as in Ledger. Note in this case the commodity symbol+appears twice; it must be the same in both places:++;commodity SYMBOL+; format SAMPLEAMOUNT++; display indian rupees with currency name on the left,+; thousands, lakhs and crores comma-separated,+; period as decimal point, and two decimal places.+commodity INR+ format INR 1,00,00,000.00++ Other indented subdirectives are currently ignored.++ Remember that if the commodity symbol contains spaces, numbers, or+punctuation, it must be enclosed in double quotes (cf Commodity).++ The amount’s quantity does not matter; only the format is+significant. It must include a decimal mark - either a period or a+comma - followed by 0 or more decimal digits.++ A few more examples:++# number formats for $, EUR, INR and the no-symbol commodity:+commodity $1,000.00+commodity EUR 1.000,00+commodity INR 9,99,99,999.0+commodity 1 000 000.++ Note hledger normally uses banker’s rounding, so 0.5 displayed with+zero decimal digits is "0". (More at Commodity display style.)++ Even in the presence of commodity directives, the commodity display+style can still be overridden by supplying a command line option.++* Menu:++* Commodity error checking::+++File: hledger.info, Node: Commodity error checking, Up: commodity directive++10.20.1 Commodity error checking+--------------------------------++In strict mode, enabled with the ‘-s’/‘--strict’ flag, hledger will+report an error if a commodity symbol is used that has not been declared+by a ‘commodity’ directive. This works similarly to account error+checking, see the notes there for more details.++ Note, this disallows amounts without a commodity symbol, because+currently it’s not possible (?) to declare the "no-symbol" commodity+with a directive. This is one exception for convenience: zero amounts+are always allowed to have no commodity symbol.+++File: hledger.info, Node: decimal-mark directive, Next: include directive, Prev: commodity directive, Up: Journal++10.21 ‘decimal-mark’ directive+==============================++You can use a ‘decimal-mark’ directive - usually one per file, at the+top of the file - to declare which character represents a decimal mark+when parsing amounts in this file. It can look like++decimal-mark .++ or++decimal-mark ,++ This prevents any ambiguity when parsing numbers in the file, so we+recommend it, especially if the file contains digit group marks (eg+thousands separators).+++File: hledger.info, Node: include directive, Next: P directive, Prev: decimal-mark directive, Up: Journal++10.22 ‘include’ directive+=========================++You can pull in the content of additional files by writing an include+directive, like this:++include FILEPATH++ Only journal files can include, and only journal, timeclock or+timedot files can be included (not CSV files, currently).++ If the file path does not begin with a slash, it is relative to the+current file’s folder.++ A tilde means home directory, eg: ‘include ~/main.journal’.++ The path may contain glob patterns to match multiple files, eg:+‘include *.journal’.++ There is limited support for recursive wildcards: ‘**/’ (the slash is+required) matches 0 or more subdirectories. It’s not super convenient+since you have to avoid include cycles and including directories, but+this can be done, eg: ‘include */**/*.journal’.++ The path may also be prefixed to force a specific file format,+overriding the file extension (as described in hledger.1 -> Input+files): ‘include timedot:~/notes/2020*.md’.+++File: hledger.info, Node: P directive, Next: payee directive, Prev: include directive, Up: Journal++10.23 ‘P’ directive+===================++The ‘P’ directive declares a market price, which is a conversion rate+between two commodities on a certain date. This allows value reports to+convert amounts of one commodity to their value in another, on or after+that date. These prices are often obtained from a stock exchange,+cryptocurrency exchange, the or foreign exchange market.++ The format is:++P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT++ DATE is a simple date, COMMODITY1SYMBOL is the symbol of the+commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and+quantity) of commodity 2 that one unit of commodity 1 is worth on this+date. Examples:++# one euro was worth $1.35 from 2009-01-01 onward:+P 2009-01-01 € $1.35++# and $1.40 from 2010-01-01 onward:+P 2010-01-01 € $1.40++ The ‘-V’, ‘-X’ and ‘--value’ flags use these market prices to show+amount values in another commodity. See Valuation.+++File: hledger.info, Node: payee directive, Next: tag directive, Prev: P directive, Up: Journal++10.24 ‘payee’ directive+=======================++‘payee PAYEE NAME’++ This directive can be used to declare a limited set of payees which+may appear in transaction descriptions. The "payees" check will report+an error if any transaction refers to a payee that has not been+declared. Eg:++payee Whole Foods++ Any indented subdirectives are currently ignored.+++File: hledger.info, Node: tag directive, Next: Periodic transactions, Prev: payee directive, Up: Journal++10.25 ‘tag’ directive+=====================++‘tag TAGNAME’++ This directive can be used to declare a limited set of tag names+allowed in tags. TAGNAME should be a valid tag name (no spaces). Eg:++tag item-id++ Any indented subdirectives are currently ignored.++ The "tags" check will report an error if any undeclared tag name is+used. It is quite easy to accidentally create a tag through normal use+of colons in comments(#comments]; if you want to prevent this, you can+declare and check your tags .+++File: hledger.info, Node: Periodic transactions, Next: Other syntax, Prev: tag directive, Up: Journal++10.26 Periodic transactions+===========================++The ‘~’ directive declares recurring transactions. Such directives+allow hledger to generate temporary future transactions (visible in+reports, not in the journal file) to help with forecasting or budgeting.++ Periodic transactions can be a little tricky, so before you use them,+read this whole section, or at least these tips:++ 1. Two spaces accidentally added or omitted will cause you trouble -+ read about this below.+ 2. For troubleshooting, show the generated transactions with ‘hledger+ print --forecast tag:generated’ or ‘hledger register --forecast+ tag:generated’.+ 3. Forecasted transactions will begin only after the last+ non-forecasted transaction’s date.+ 4. Forecasted transactions will end 6 months from today, by default.+ See below for the exact start/end rules.+ 5. period expressions can be tricky. Their documentation needs+ improvement, but is worth studying.+ 6. Some period expressions with a repeating interval must begin on a+ natural boundary of that interval. Eg in ‘weekly from DATE’, DATE+ must be a monday. ‘~ weekly from 2019/10/1’ (a tuesday) will give+ an error.+ 7. Other period expressions with an interval are automatically+ expanded to cover a whole number of that interval. (This is done+ to improve reports, but it also affects periodic transactions.+ Yes, it’s a bit inconsistent with the above.) Eg: ‘~ every 10th+ day of month from 2020/01’, which is equivalent to ‘~ every 10th+ day of month from 2020/01/01’, will be adjusted to start on+ 2019/12/10.++* Menu:++* Periodic rule syntax::+* Periodic rules and relative dates::+* Two spaces between period expression and description!::+++File: hledger.info, Node: Periodic rule syntax, Next: Periodic rules and relative dates, Up: Periodic transactions++10.26.1 Periodic rule syntax+----------------------------++A periodic transaction rule looks like a normal journal entry, with the+date replaced by a tilde (‘~’) followed by a period expression+(mnemonic: ‘~’ looks like a recurring sine wave.):++# every first of month+~ monthly+ expenses:rent $2000+ assets:bank:checking++# every 15th of month in 2023's first quarter:+~ monthly from 2023-04-15 to 2023-06-16+ expenses:utilities $400+ assets:bank:checking++ The period expression is the same syntax used for specifying+multi-period reports, just interpreted differently; there, it specifies+report periods; here it specifies recurrence dates (the periods’ start+dates).+++File: hledger.info, Node: Periodic rules and relative dates, Next: Two spaces between period expression and description!, Prev: Periodic rule syntax, Up: Periodic transactions++10.26.2 Periodic rules and relative dates+-----------------------------------------++Partial or relative dates (like ‘12/31’, ‘25’, ‘tomorrow’, ‘last week’,+‘next quarter’) are usually not recommended in periodic rules, since the+results will change as time passes. If used, they will be interpreted+relative to, in order of preference:++ 1. the first day of the default year specified by a recent ‘Y’+ directive+ 2. or the date specified with ‘--today’+ 3. or the date on which you are running the report.++ They will not be affected at all by report period or forecast period+dates.+++File: hledger.info, Node: Two spaces between period expression and description!, Prev: Periodic rules and relative dates, Up: Periodic transactions++10.26.3 Two spaces between period expression and description!+-------------------------------------------------------------++If the period expression is followed by a transaction description, these+must be separated by *two or more spaces*. This helps hledger know+where the period expression ends, so that descriptions can not+accidentally alter their meaning, as in this example:++; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2020"+; ||+; vv+~ every 2 months in 2020, we will review+ assets:bank:checking $1500+ income:acme inc++ So,++ • Do write two spaces between your period expression and your+ transaction description, if any.+ • Don’t accidentally write two spaces in the middle of your period+ expression.+++File: hledger.info, Node: Other syntax, Prev: Periodic transactions, Up: Journal++10.27 Other syntax+==================++hledger journal format supports quite a few other features, mainly to+make interoperating with or converting from Ledger easier. Note some of+the features below are powerful and can be useful in special cases, but+in general, features in this section are considered less important or+even not recommended for most users. Downsides are mentioned to help+you decide if you want to use them.++* Menu:++* Auto postings::+* Balance assignments::+* Bracketed posting dates::+* D directive::+* apply account directive::+* Y directive::+* Secondary dates::+* Star comments::+* Valuation expressions::+* Virtual postings::+* Other Ledger directives::+++File: hledger.info, Node: Auto postings, Next: Balance assignments, Up: Other syntax++10.27.1 Auto postings+---------------------++The ‘=’ directive declares a rule for automatically adding temporary+extra postings (visible in reports, not in the journal file) to all+transactions matched by a certain query, when you use the ‘--auto’ flag.++ Downsides: depending on generated data for your reports makes your+financial data less portable, less future-proof, and less trustworthy in+an audit. Also, because the feature is optional, other features like+balance assertions can break depending on whether it is on or off.++ An auto posting rule looks a bit like a transaction:++= QUERY+ ACCOUNT AMOUNT+ ...+ ACCOUNT [AMOUNT]++ except the first line is an equals sign (mnemonic: ‘=’ suggests+matching), followed by a query (which matches existing postings), and+each "posting" line describes a posting to be generated, and the posting+amounts can be:++ • a normal amount with a commodity symbol, eg ‘$2’. This will be+ used as-is.+ • a number, eg ‘2’. The commodity symbol (if any) from the matched+ posting will be added to this.+ • a numeric multiplier, eg ‘*2’ (a star followed by a number N). The+ matched posting’s amount (and total price, if any) will be+ multiplied by N.+ • a multiplier with a commodity symbol, eg ‘*$2’ (a star, number N,+ and symbol S). The matched posting’s amount will be multiplied by+ N, and its commodity symbol will be replaced with S.++ Any query term containing spaces must be enclosed in single or double+quotes, as on the command line. Eg, note the quotes around the second+query term below:++= expenses:groceries 'expenses:dining out'+ (budget:funds:dining out) *-1++ Some examples:++; every time I buy food, schedule a dollar donation+= expenses:food+ (liabilities:charity) $-1++; when I buy a gift, also deduct that amount from a budget envelope subaccount+= expenses:gifts+ assets:checking:gifts *-1+ assets:checking *1++2017/12/1+ expenses:food $10+ assets:checking++2017/12/14+ expenses:gifts $20+ assets:checking++$ hledger print --auto+2017-12-01+ expenses:food $10+ assets:checking+ (liabilities:charity) $-1++2017-12-14+ expenses:gifts $20+ assets:checking+ assets:checking:gifts -$20+ assets:checking $20++* Menu:++* Auto postings and multiple files::+* Auto postings and dates::+* Auto postings and transaction balancing / inferred amounts / balance assertions::+* Auto posting tags::+++File: hledger.info, Node: Auto postings and multiple files, Next: Auto postings and dates, Up: Auto postings++10.27.1.1 Auto postings and multiple files+..........................................++An auto posting rule can affect any transaction in the current file, or+in any parent file or child file. Note, currently it will not affect+sibling files (when multiple ‘-f’/‘--file’ are used - see #1212).+++File: hledger.info, Node: Auto postings and dates, Next: Auto postings and transaction balancing / inferred amounts / balance assertions, Prev: Auto postings and multiple files, Up: Auto postings++10.27.1.2 Auto postings and dates+.................................++A posting date (or secondary date) in the matched posting, or (taking+precedence) a posting date in the auto posting rule itself, will also be+used in the generated posting.+++File: hledger.info, Node: Auto postings and transaction balancing / inferred amounts / balance assertions, Next: Auto posting tags, Prev: Auto postings and dates, Up: Auto postings++10.27.1.3 Auto postings and transaction balancing / inferred+............................................................++amounts / balance assertions Currently, auto postings are added:++ • after missing amounts are inferred, and transactions are checked+ for balancedness,+ • but before balance assertions are checked.++ Note this means that journal entries must be balanced both before and+after auto postings are added. This changed in hledger 1.12+; see #893+for background.++ This also means that you cannot have more than one auto-posting with+a missing amount applied to a given transaction, as it will be unable to+infer amounts.+++File: hledger.info, Node: Auto posting tags, Prev: Auto postings and transaction balancing / inferred amounts / balance assertions, Up: Auto postings++10.27.1.4 Auto posting tags+...........................++Automated postings will have some extra tags:++ • ‘generated-posting:= QUERY’ - shows this was generated by an auto+ posting rule, and the query+ • ‘_generated-posting:= QUERY’ - a hidden tag, which does not appear+ in hledger’s output. This can be used to match postings generated+ "just now", rather than generated in the past and saved to the+ journal.++ Also, any transaction that has been changed by auto posting rules+will have these tags added:++ • ‘modified:’ - this transaction was modified+ • ‘_modified:’ - a hidden tag not appearing in the comment; this+ transaction was modified "just now".+++File: hledger.info, Node: Balance assignments, Next: Bracketed posting dates, Prev: Auto postings, Up: Other syntax++10.27.2 Balance assignments+---------------------------++Ledger-style balance assignments are also supported. These are like+balance assertions, but with no posting amount on the left side of the+equals sign; instead it is calculated automatically so as to satisfy the+assertion. This can be a convenience during data entry, eg when setting+opening balances:++; starting a new journal, set asset account balances+2016/1/1 opening balances+ assets:checking = $409.32+ assets:savings = $735.24+ assets:cash = $42+ equity:opening balances++ or when adjusting a balance to reality:++; no cash left; update balance, record any untracked spending as a generic expense+2016/1/15+ assets:cash = $0+ expenses:misc++ The calculated amount depends on the account’s balance in the+commodity at that point (which depends on the previously-dated postings+of the commodity to that account since the last balance assertion or+assignment).++ Downsides: using balance assignments makes your journal less+explicit; to know the exact amount posted, you have to run hledger or do+the calculations yourself, instead of just reading it. Also balance+assignments’ forcing of balances can hide errors. These things make+your financial data less portable, less future-proof, and less+trustworthy in an audit.++* Menu:++* Balance assignments and prices::+++File: hledger.info, Node: Balance assignments and prices, Up: Balance assignments++10.27.2.1 Balance assignments and prices+........................................++A cost in a balance assignment will cause the calculated amount to have+that price attached:++2019/1/1+ (a) = $1 @ €2++$ hledger print --explicit+2019-01-01+ (a) $1 @ €2 = $1 @ €2+++File: hledger.info, Node: Bracketed posting dates, Next: D directive, Prev: Balance assignments, Up: Other syntax++10.27.3 Bracketed posting dates+-------------------------------++For setting posting dates and secondary posting dates, Ledger’s+bracketed date syntax is also supported: ‘[DATE]’, ‘[DATE=DATE2]’ or+‘[=DATE2]’ in posting comments. hledger will attempt to parse any+square-bracketed sequence of the ‘0123456789/-.=’ characters in this+way. With this syntax, DATE infers its year from the transaction and+DATE2 infers its year from DATE.++ Downsides: another syntax to learn, redundant with hledger’s+‘date:’/‘date2:’ tags, and confusingly similar to Ledger’s lot date+syntax.+++File: hledger.info, Node: D directive, Next: apply account directive, Prev: Bracketed posting dates, Up: Other syntax++10.27.4 ‘D’ directive+---------------------++‘D AMOUNT’++ This directive sets a default commodity, to be used for any+subsequent commodityless amounts (ie, plain numbers) seen while parsing+the journal. This effect lasts until the next ‘D’ directive, or the end+of the journal.++ For compatibility/historical reasons, ‘D’ also acts like a+‘commodity’ directive (setting the commodity’s decimal mark for parsing+and display style for output). So its argument is not just a commodity+symbol, but a full amount demonstrating the style. The amount must+include a decimal mark (either period or comma). Eg:++; commodity-less amounts should be treated as dollars+; (and displayed with the dollar sign on the left, thousands separators and two decimal places)+D $1,000.00++1/1+ a 5 ; <- commodity-less amount, parsed as $5 and displayed as $5.00+ b++ Interactions with other directives:++ For setting a commodity’s display style, a ‘commodity’ directive has+highest priority, then a ‘D’ directive.++ For detecting a commodity’s decimal mark during parsing,+‘decimal-mark’ has highest priority, then ‘commodity’, then ‘D’.++ For checking commodity symbols with the check command, a ‘commodity’+directive is required (‘hledger check commodities’ ignores ‘D’+directives).++ Downsides: omitting commodity symbols makes your financial data less+explicit, less portable, and less trustworthy in an audit. It is+usually an unsustainable shortcut; sooner or later you will want to+track multiple commodities. D is overloaded with functions redundant+with ‘commodity’ and ‘decimal-mark’. And it works differently from+Ledger’s ‘D’.+++File: hledger.info, Node: apply account directive, Next: Y directive, Prev: D directive, Up: Other syntax++10.27.5 ‘apply account’ directive+---------------------------------++This directive sets a default parent account, which will be prepended to+all accounts in following entries, until an ‘end apply account’+directive or end of current file. Eg:++apply account home++2010/1/1+ food $10+ cash++end apply account++ is equivalent to:++2010/01/01+ home:food $10+ home:cash $-10++ ‘account’ directives are also affected, and so is any ‘include’d+content.++ Account names entered via hledger add or hledger-web are not+affected.++ Account aliases, if any, are applied after the parent account is+prepended.++ Downsides: this can make your financial data less explicit, less+portable, and less trustworthy in an audit.+++File: hledger.info, Node: Y directive, Next: Secondary dates, Prev: apply account directive, Up: Other syntax++10.27.6 ‘Y’ directive+---------------------++‘Y YEAR’++ or (deprecated backward-compatible forms):++ ‘year YEAR’ ‘apply year YEAR’++ The space is optional. This sets a default year to be used for+subsequent dates which don’t specify a year. Eg:++Y2009 ; set default year to 2009++12/15 ; equivalent to 2009/12/15+ expenses 1+ assets++year 2010 ; change default year to 2010++2009/1/30 ; specifies the year, not affected+ expenses 1+ assets++1/31 ; equivalent to 2010/1/31+ expenses 1+ assets++ Downsides: omitting the year (from primary transaction dates, at+least) makes your financial data less explicit, less portable, and less+trustworthy in an audit. Such dates can get separated from their+corresponding Y directive, eg when evaluating a region of the journal in+your editor. A missing Y directive makes reports dependent on today’s+date.+++File: hledger.info, Node: Secondary dates, Next: Star comments, Prev: Y directive, Up: Other syntax++10.27.7 Secondary dates+-----------------------++A secondary date is written after the primary date, following an equals+sign. If the year is omitted, the primary date’s year is assumed. When+running reports, the primary (left) date is used by default, but with+the ‘--date2’ flag (or ‘--aux-date’ or ‘--effective’), the secondary+(right) date will be used instead.++ The meaning of secondary dates is up to you, but it’s best to follow+a consistent rule. Eg "primary = the bank’s clearing date, secondary =+date the transaction was initiated, if different".++ Downsides: makes your financial data more complicated, less portable,+and less trustworthy in an audit. Keeping the meaning of the two dates+consistent requires discipline, and you have to remember which reporting+mode is appropriate for a given report. Posting dates are simpler and+better.+++File: hledger.info, Node: Star comments, Next: Valuation expressions, Prev: Secondary dates, Up: Other syntax++10.27.8 Star comments+---------------------++Lines beginning with ‘*’ (star/asterisk) are also comment lines. This+feature allows Emacs users to insert org headings in their journal,+allowing them to fold/unfold/navigate it like an outline when viewed+with org mode.++ Downsides: another, unconventional comment syntax to learn.+Decreases your journal’s portability. And switching to Emacs org mode+just for folding/unfolding meant losing the benefits of ledger mode;+nowadays you can add outshine mode to ledger mode to get folding without+losing ledger mode’s features.+++File: hledger.info, Node: Valuation expressions, Next: Virtual postings, Prev: Star comments, Up: Other syntax++10.27.9 Valuation expressions+-----------------------------++Ledger allows a valuation function or value to be written in double+parentheses after an amount. hledger ignores these.+++File: hledger.info, Node: Virtual postings, Next: Other Ledger directives, Prev: Valuation expressions, Up: Other syntax++10.27.10 Virtual postings+-------------------------++A posting with parentheses around the account name is called a _virtual+posting_ or _unbalanced posting_, which means it is exempt from the+usual rule that a transaction’s postings must balance add up to zero.++ This is not part of double entry bookkeeping, so you might choose to+avoid this feature. Or you can use it sparingly for certain special+cases where it can be convenient. Eg, you could set opening balances+without using a balancing equity account:++2022-01-01 opening balances+ (assets:checking) $1000+ (assets:savings) $2000++ A posting with brackets around the account name is called a _balanced+virtual posting_. The balanced virtual postings in a transaction must+add up to zero (separately from other postings). Eg:++2022-01-01 buy food with cash, update budget envelope subaccounts, & something else+ assets:cash $-10 ; <- these balance each other+ expenses:food $7 ; <-+ expenses:food $3 ; <-+ [assets:checking:budget:food] $-10 ; <- and these balance each other+ [assets:checking:available] $10 ; <-+ (something:else) $5 ; <- this is not required to balance++ Postings whose account names are neither parenthesised nor bracketed+are called _real postings_. You can exclude virtual postings from+reports with the ‘-R/--real’ flag or a ‘real:1’ query.++ Downsides: violates double entry bookkeeping, can be used to avoid+figuring out correct entries, makes your financial data less portable+and less trustworthy in an audit.+++File: hledger.info, Node: Other Ledger directives, Prev: Virtual postings, Up: Other syntax++10.27.11 Other Ledger directives+--------------------------------++These other Ledger directives are currently accepted but ignored. This+allows hledger to read more Ledger files, but be aware that hledger’s+reports may differ from Ledger’s if you use these.++apply fixed COMM AMT+apply tag TAG+assert EXPR+bucket / A ACCT+capture ACCT REGEX+check EXPR+define VAR=EXPR+end apply fixed+end apply tag+end apply year+end tag+eval / expr EXPR+python+ PYTHONCODE+tag NAME+value EXPR+--command-line-flags++ See also https://hledger.org/ledger.html for a detailed+hledger/Ledger syntax comparison.+++File: hledger.info, Node: CSV, Next: Timeclock, Prev: Journal, Up: Top++11 CSV+******++hledger can read CSV files (Character Separated Value - usually comma,+semicolon, or tab) containing dated records, automatically converting+each record into a transaction.++ (To learn about _writing_ CSV, see CSV output.)++ For best error messages when reading CSV/TSV/SSV files, make sure+they have a corresponding ‘.csv’, ‘.tsv’ or ‘.ssv’ file extension or use+a hledger file prefix (see File Extension below).++ Each CSV file must be described by a corresponding _rules file_.+This contains rules describing the CSV data (header line, fields layout,+date format etc.), how to construct hledger transactions from it, and+how to categorise transactions based on description or other attributes.++ By default hledger looks for a rules file named like the CSV file+with an extra ‘.rules’ extension, in the same directory. Eg when asked+to read ‘foo/FILE.csv’, hledger looks for ‘foo/FILE.csv.rules’. You can+specify a different rules file with the ‘--rules-file’ option. If no+rules file is found, hledger will create a sample rules file, which+you’ll need to adjust.++ At minimum, the rules file must identify the date and amount fields,+and often it also specifies the date format and how many header lines+there are. Here’s a simple CSV file and a rules file for it:++Date, Description, Id, Amount+12/11/2019, Foo, 123, 10.23++# basic.csv.rules+skip 1+fields date, description, , amount+date-format %d/%m/%Y++$ hledger print -f basic.csv+2019-11-12 Foo+ expenses:unknown 10.23+ income:unknown -10.23++ There’s an introductory Importing CSV data tutorial on hledger.org,+and more CSV rules examples below, and a larger collection at+https://github.com/simonmichael/hledger/tree/master/examples/csv.++* Menu:++* CSV rules cheatsheet::+* separator::+* skip::+* date-format::+* timezone::+* newest-first::+* intra-day-reversed::+* decimal-mark::+* fields list::+* Field assignment::+* Field names::+* if block::+* Matchers::+* if table::+* balance-type::+* include::+* Working with CSV::+* CSV rules examples::+++File: hledger.info, Node: CSV rules cheatsheet, Next: separator, Up: CSV++11.1 CSV rules cheatsheet+=========================++The following kinds of rule can appear in the rules file, in any order.+(Blank lines and lines beginning with ‘#’ or ‘;’ or ‘*’ are ignored.)++*‘separator’* declare the field separator, instead of+ relying on file extension+*‘skip’* skip one or more header lines at start of file+*‘date-format’* declare how to parse CSV dates/date-times+*‘timezone’* declare the time zone of ambiguous CSV+ date-times+*‘newest-first’* improve txn order when: there are multiple+ records, newest first, all with the same date+*‘intra-day-reversed’* improve txn order when: same-day txns are in+ opposite order to the overall file+*‘decimal-mark’* declare the decimal mark used in CSV amounts,+ when ambiguous+*‘fields’ list* name CSV fields for easy reference, and+ optionally assign their values to hledger+ fields+*Field assignment* assign a CSV value or interpolated text value+ to a hledger field+*‘if’ block* conditionally assign values to hledger fields,+ or ‘skip’ a record or ‘end’ (skip rest of+ file)+*‘if’ table* conditionally assign values to hledger fields,+ using compact syntax+*‘balance-type’* select which type of balance+ assertions/assignments to generate+*‘include’* inline another CSV rules file++ Working with CSV tips can be found below, including How CSV rules are+evaluated.+++File: hledger.info, Node: separator, Next: skip, Prev: CSV rules cheatsheet, Up: CSV++11.2 ‘separator’+================++You can use the ‘separator’ rule to read other kinds of+character-separated data. The argument is any single separator+character, or the words ‘tab’ or ‘space’ (case insensitive). Eg, for+comma-separated values (CSV):++separator ,++ or for semicolon-separated values (SSV):++separator ;++ or for tab-separated values (TSV):++separator TAB++ If the input file has a ‘.csv’, ‘.ssv’ or ‘.tsv’ file extension (or a+‘csv:’, ‘ssv:’, ‘tsv:’ prefix), the appropriate separator will be+inferred automatically, and you won’t need this rule.+++File: hledger.info, Node: skip, Next: date-format, Prev: separator, Up: CSV++11.3 ‘skip’+===========++skip N++ The word ‘skip’ followed by a number (or no number, meaning 1) tells+hledger to ignore this many non-empty lines at the start of the input+data. (Empty/blank lines are skipped automatically, so you don’t need+to count those.) You’ll need this whenever your CSV data contains+header lines. Header lines skipped in this way are ignored, and not+parsed as CSV.++ ‘skip’ can also be used inside if blocks (described below), to skip+individual data records. Note records skipped in this way are still+required to be valid CSV, even though otherwise ignored.+++File: hledger.info, Node: date-format, Next: timezone, Prev: skip, Up: CSV++11.4 ‘date-format’+==================++date-format DATEFMT++ This is a helper for the ‘date’ (and ‘date2’) fields. If your CSV+dates are not formatted like ‘YYYY-MM-DD’, ‘YYYY/MM/DD’ or ‘YYYY.MM.DD’,+you’ll need to add a date-format rule describing them with a+strptime-style date parsing pattern - see+https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime.+The pattern must parse the CSV date value completely. Some examples:++# MM/DD/YY+date-format %m/%d/%y++# D/M/YYYY+# The - makes leading zeros optional.+date-format %-d/%-m/%Y++# YYYY-Mmm-DD+date-format %Y-%h-%d++# M/D/YYYY HH:MM AM some other junk+# Note the time and junk must be fully parsed, though only the date is used.+date-format %-m/%-d/%Y %l:%M %p some other junk+++File: hledger.info, Node: timezone, Next: newest-first, Prev: date-format, Up: CSV++11.5 ‘timezone’+===============++timezone TIMEZONE++ When CSV contains date-times that are implicitly in some time zone+other than yours, but containing no explicit time zone information, you+can use this rule to declare the CSV’s native time zone, which helps+prevent off-by-one dates.++ When the CSV date-times do contain time zone information, you don’t+need this rule; instead, use ‘%Z’ in ‘date-format’ (or ‘%z’, ‘%EZ’,+‘%Ez’; see the formatTime link above).++ In either of these cases, hledger will do a time-zone-aware+conversion, localising the CSV date-times to your current system time+zone. If you prefer to localise to some other time zone, eg for+reproducibility, you can (on unix at least) set the output timezone with+the TZ environment variable, eg:++$ TZ=-1000 hledger print -f foo.csv # or TZ=-1000 hledger import foo.csv++ ‘timezone’ currently does not understand timezone names, except+"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".+For others, use numeric format: +HHMM or -HHMM.+++File: hledger.info, Node: newest-first, Next: intra-day-reversed, Prev: timezone, Up: CSV++11.6 ‘newest-first’+===================++hledger tries to ensure that the generated transactions will be ordered+chronologically, including intra-day transactions. Usually it can+auto-detect how the CSV records are ordered. But if it encounters CSV+where all records are on the same date, it assumes that the records are+oldest first. If in fact the CSV’s records are normally newest first,+like:++2022-10-01, txn 3...+2022-10-01, txn 2...+2022-10-01, txn 1...++ you can add the ‘newest-first’ rule to help hledger generate the+transactions in correct order.++# same-day CSV records are newest first+newest-first+++File: hledger.info, Node: intra-day-reversed, Next: decimal-mark, Prev: newest-first, Up: CSV++11.7 ‘intra-day-reversed’+=========================++CSV records for each day are sometimes ordered in reverse compared to+the overall date order. Eg, here dates are newest first, but the+transactions on each date are oldest first:++2022-10-02, txn 3...+2022-10-02, txn 4...+2022-10-01, txn 1...+2022-10-01, txn 2...++ In this situation, add the ‘intra-day-reversed’ rule, and hledger+will compensate, improving the order of transactions.++# transactions within each day are reversed with respect to the overall date order+intra-day-reversed+++File: hledger.info, Node: decimal-mark, Next: fields list, Prev: intra-day-reversed, Up: CSV++11.8 ‘decimal-mark’+===================++decimal-mark .++ or:++decimal-mark ,++ hledger automatically accepts either period or comma as a decimal+mark when parsing numbers (cf Amounts). However if any numbers in the+CSV contain digit group marks, such as thousand-separating commas, you+should declare the decimal mark explicitly with this rule, to avoid+misparsed numbers.+++File: hledger.info, Node: fields list, Next: Field assignment, Prev: decimal-mark, Up: CSV++11.9 ‘fields’ list+==================++fields FIELDNAME1, FIELDNAME2, ...++ A fields list (the word ‘fields’ followed by comma-separated field+names) is optional, but convenient. It does two things:++ 1. It names the CSV field in each column. This can be convenient if+ you are referencing them in other rules, so you can say+ ‘%SomeField’ instead of remembering ‘%13’.++ 2. Whenever you use one of the special hledger field names (described+ below), it assigns the CSV value in this position to that hledger+ field. This is the quickest way to populate hledger’s fields and+ build a transaction.++ Here’s an example that says "use the 1st, 2nd and 4th fields as the+transaction’s date, description and amount; name the last two fields for+later reference; and ignore the others":++fields date, description, , amount, , , somefield, anotherfield++ In a fields list, the separator is always comma; it is unrelated to+the CSV file’s separator. Also:++ • There must be least two items in the list (at least one comma).+ • Field names may not contain spaces. Spaces before/after field+ names are optional.+ • Field names may contain ‘_’ (underscore) or ‘-’ (hyphen).+ • Fields you don’t care about can be given a dummy name or an empty+ name.++ If the CSV contains column headings, it’s convenient to use these for+your field names, suitably modified (eg lower-cased with spaces replaced+by underscores).++ Sometimes you may want to alter a CSV field name to avoid assigning+to a hledger field with the same name. Eg you could call the CSV’s+"balance" field ‘balance_’ to avoid directly setting hledger’s ‘balance’+field (and generating a balance assertion).+++File: hledger.info, Node: Field assignment, Next: Field names, Prev: fields list, Up: CSV++11.10 Field assignment+======================++HLEDGERFIELD FIELDVALUE++ Field assignments are the more flexible way to assign CSV values to+hledger fields. They can be used instead of or in addition to a fields+list (see above).++ To assign a value to a hledger field, write the field name (any of+the standard hledger field/pseudo-field names, defined below), a space,+followed by a text value on the same line. This text value may+interpolate CSV fields, referenced by their 1-based position in the CSV+record (‘%N’), or by the name they were given in the fields list+(‘%CSVFIELD’).++ Some examples:++# set the amount to the 4th CSV field, with " USD" appended+amount %4 USD++# combine three fields to make a comment, containing note: and date: tags+comment note: %somefield - %anotherfield, date: %1++ Tips:++ • Interpolation strips outer whitespace (so a CSV value like ‘" 1 "’+ becomes ‘1’ when interpolated) (#1051).+ • Interpolations always refer to a CSV field - you can’t interpolate+ a hledger field. (See Referencing other fields below).+++File: hledger.info, Node: Field names, Next: if block, Prev: Field assignment, Up: CSV++11.11 Field names+=================++Note the two kinds of field names mentioned here, and used only in+hledger CSV rules files:++ 1. *CSV field names* (‘CSVFIELD’ in these docs): you can optionally+ name the CSV columns for easy reference (since hledger doesn’t yet+ automatically recognise column headings in a CSV file), by writing+ arbitrary names in a ‘fields’ list, eg:++ fields When, What, Some_Id, Net, Total, Foo, Bar++ 2. Special *hledger field names* (‘HLEDGERFIELD’ in these docs): you+ must set at least some of these to generate the hledger transaction+ from a CSV record, by writing them as the left hand side of a field+ assignment, eg:++ date %When+ code %Some_Id+ description %What+ comment %Foo %Bar+ amount1 $ %Total++ or directly in a ‘fields’ list:++ fields date, description, code, , amount1, Foo, Bar+ currency $+ comment %Foo %Bar++ Here are all the special hledger field names available, and what+happens when you assign values to them:++* Menu:++* date field::+* date2 field::+* status field::+* code field::+* description field::+* comment field::+* account field::+* amount field::+* currency field::+* balance field::+++File: hledger.info, Node: date field, Next: date2 field, Up: Field names++11.11.1 date field+------------------++Assigning to ‘date’ sets the transaction date.+++File: hledger.info, Node: date2 field, Next: status field, Prev: date field, Up: Field names++11.11.2 date2 field+-------------------++‘date2’ sets the transaction’s secondary date, if any.+++File: hledger.info, Node: status field, Next: code field, Prev: date2 field, Up: Field names++11.11.3 status field+--------------------++‘status’ sets the transaction’s status, if any.+++File: hledger.info, Node: code field, Next: description field, Prev: status field, Up: Field names++11.11.4 code field+------------------++‘code’ sets the transaction’s code, if any.+++File: hledger.info, Node: description field, Next: comment field, Prev: code field, Up: Field names++11.11.5 description field+-------------------------++‘description’ sets the transaction’s description, if any.+++File: hledger.info, Node: comment field, Next: account field, Prev: description field, Up: Field names++11.11.6 comment field+---------------------++‘comment’ sets the transaction’s comment, if any.++ ‘commentN’, where N is a number, sets the Nth posting’s comment.++ You can assign multi-line comments by writing literal ‘\n’ in the+code. A comment starting with ‘\n’ will begin on a new line.++ Comments can contain tags, as usual.+++File: hledger.info, Node: account field, Next: amount field, Prev: comment field, Up: Field names++11.11.7 account field+---------------------++Assigning to ‘accountN’, where N is 1 to 99, sets the account name of+the Nth posting, and causes that posting to be generated.++ Most often there are two postings, so you’ll want to set ‘account1’+and ‘account2’. Typically ‘account1’ is associated with the CSV file,+and is set once with a top-level assignment, while ‘account2’ is set+based on each transaction’s description, in conditional rules.++ If a posting’s account name is left unset but its amount is set (see+below), a default account name will be chosen (like "expenses:unknown"+or "income:unknown").+++File: hledger.info, Node: amount field, Next: currency field, Prev: account field, Up: Field names++11.11.8 amount field+--------------------++There are several "amount" field name variants, useful for different+situations:++ • ‘amountN’ sets the amount of the Nth posting, and causes that+ posting to be generated. By assigning to ‘amount1’, ‘amount2’, ...+ etc. you can generate up to 99 postings. Posting numbers don’t+ have to be consecutive; in certain situations using a high number+ might be helpful to influence the layout of postings.++ • ‘amountN-in’ and ‘amountN-out’ should be used instead, as a pair,+ when and only when the amount must be obtained from two CSV fields.+ Eg when the CSV has separate Debit and Credit fields instead of a+ single Amount field. Note:++ • Don’t think "-in is for the first posting and -out is for the+ second posting" - that’s not correct. Think: "‘amountN-in’+ and ‘amountN-out’ together detect the amount for posting N, by+ inspecting two CSV fields at once."+ • hledger assumes both CSV fields are unsigned, and will+ automatically negate the -out value.+ • It also expects that at least one of the values is empty or+ zero, so it knows which one to ignore. If that’s not the case+ you’ll need an if rule (see Setting amounts below).++ • ‘amount’, with no posting number (and similarly, ‘amount-in’ and+ ‘amount-out’ with no number) are an older syntax. We keep them for+ backwards compatibility, and because they have special behaviour+ that is sometimes convenient:++ • They set the amount of posting 1 and (negated) the amount of+ posting 2.+ • Posting 2’s amount will be converted to cost if it has a cost+ price.+ • Any of the newer rules for posting 1 or 2 (like ‘amount1’, or+ ‘amount2-in’ and ‘amount2-out’) will take precedence. This+ allows incrementally migrating old rules files to the new+ syntax.++ There’s more to say about amount-setting that doesn’t fit here;+please see also "Setting amounts" below.+++File: hledger.info, Node: currency field, Next: balance field, Prev: amount field, Up: Field names++11.11.9 currency field+----------------------++‘currency’ sets a currency symbol, to be prepended to all postings’+amounts. You can use this if the CSV amounts do not have a currency+symbol, eg if it is in a separate column.++ ‘currencyN’ prepends a currency symbol to just the Nth posting’s+amount.+++File: hledger.info, Node: balance field, Prev: currency field, Up: Field names++11.11.10 balance field+----------------------++‘balanceN’ sets a balance assertion amount (or if the posting amount is+left empty, a balance assignment) on posting N.++ ‘balance’ is a compatibility spelling for hledger <1.17; it is+equivalent to ‘balance1’.++ You can adjust the type of assertion/assignment with the+‘balance-type’ rule (see below).++ See Tips below for more about setting amounts and currency.+++File: hledger.info, Node: if block, Next: Matchers, Prev: Field names, Up: CSV++11.12 ‘if’ block+================++Rules can be applied conditionally, depending on patterns in the CSV+data. This allows flexibility; in particular, it is how you can+categorise transactions, selecting an appropriate account name based on+their description (for example). There are two ways to write+conditional rules: "if blocks", described here, and "if tables",+described below.++ An if block is the word ‘if’ and one or more "matcher" expressions+(can be a word or phrase), one per line, starting either on the same or+next line; followed by one or more indented rules. Eg,++if MATCHER+ RULE++ or++if+MATCHER+MATCHER+MATCHER+ RULE+ RULE++ If any of the matchers succeeds, all of the indented rules will be+applied. They are usually field assignments, but the following special+rules may also be used within an if block:++ • ‘skip’ - skips the matched CSV record (generating no transaction+ from it)+ • ‘end’ - skips the rest of the current CSV file.++ Some examples:++# if the record contains "groceries", set account2 to "expenses:groceries"+if groceries+ account2 expenses:groceries++# if the record contains any of these phrases, set account2 and a transaction comment as shown+if+monthly service fee+atm transaction fee+banking thru software+ account2 expenses:business:banking+ comment XXX deductible ? check it++# if an empty record is seen (assuming five fields), ignore the rest of the CSV file+if ,,,,+ end+++File: hledger.info, Node: Matchers, Next: if table, Prev: if block, Up: CSV++11.13 Matchers+==============++There are two kinds:++ 1. A record matcher is a word or single-line text fragment or regular+ expression (‘REGEX’), which hledger will try to match+ case-insensitively anywhere within the CSV record.+ Eg: ‘whole foods’++ 2. A field matcher is preceded with a percent sign and CSV field name+ (‘%CSVFIELD REGEX’). hledger will try to match these just within+ the named CSV field.+ Eg: ‘%date 2023’++ The regular expression is (as usual in hledger) a POSIX extended+regular expression, that also supports GNU word boundaries (‘\b’, ‘\B’,+‘\<’, ‘\>’), and nothing else. If you have trouble, see "Regular+expressions" in the hledger manual+(https://hledger.org/hledger.html#regular-expressions).++ With record matchers, it’s important to know that the record matched+is not the original CSV record, but a modified one: separators will be+converted to commas, and enclosing double quotes (but not enclosing+whitespace) are removed. So for example, when reading an SSV file, if+the original record was:++2020-01-01; "Acme, Inc."; 1,000++ the regex would see, and try to match, this modified record text:++2020-01-01,Acme, Inc., 1,000++ When an if block has multiple matchers, they are combined as follows:++ • By default they are OR’d (any one of them can match)+ • When a matcher is preceded by ampersand (‘&’) it will be AND’ed+ with the previous matcher (both of them must match).++ There’s not yet an easy syntax to negate a matcher.+++File: hledger.info, Node: if table, Next: balance-type, Prev: Matchers, Up: CSV++11.14 ‘if’ table+================++"if tables" are an alternative to if blocks; they can express many+matchers and field assignments in a more compact tabular format, like+this:++if,HLEDGERFIELD1,HLEDGERFIELD2,...+MATCHERA,VALUE1,VALUE2,...+MATCHERB,VALUE1,VALUE2,...+MATCHERC,VALUE1,VALUE2,...+<empty line>++ The first character after ‘if’ is taken to be the separator for the+rest of the table. It should be a non-alphanumeric character like ‘,’+or ‘|’ that does not appear anywhere else in the table. (Note: it is+unrelated to the CSV file’s separator.) Whitespace can be used in the+matcher lines for readability, but not in the if line currently. The+table must be terminated by an empty line (or end of file). Each line+must contain the same number of separators; empty values are allowed.++ The above means: try all of the matchers; whenever a matcher+succeeds, assign all of the values on that line to the corresponding+hledger fields; later lines can overrider earlier ones. It is+equivalent to this sequence of if blocks:++if MATCHERA+ HLEDGERFIELD1 VALUE1+ HLEDGERFIELD2 VALUE2+ ...++if MATCHERB+ HLEDGERFIELD1 VALUE1+ HLEDGERFIELD2 VALUE2+ ...++if MATCHERC+ HLEDGERFIELD1 VALUE1+ HLEDGERFIELD2 VALUE2+ ...++ Example:++if,account2,comment+atm transaction fee,expenses:business:banking,deductible? check it+%description groceries,expenses:groceries,+2020/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out+++File: hledger.info, Node: balance-type, Next: include, Prev: if table, Up: CSV++11.15 ‘balance-type’+====================++Balance assertions generated by assigning to balanceN are of the simple+‘=’ type by default, which is a single-commodity, subaccount-excluding+assertion. You may find the subaccount-including variants more useful,+eg if you have created some virtual subaccounts of checking to help with+budgeting. You can select a different type of assertion with the+‘balance-type’ rule:++# balance assertions will consider all commodities and all subaccounts+balance-type ==*++ Here are the balance assertion types for quick reference:++= single commodity, exclude subaccounts+=* single commodity, include subaccounts+== multi commodity, exclude subaccounts+==* multi commodity, include subaccounts+++File: hledger.info, Node: include, Next: Working with CSV, Prev: balance-type, Up: CSV++11.16 ‘include’+===============++include RULESFILE++ This includes the contents of another CSV rules file at this point.+‘RULESFILE’ is an absolute file path or a path relative to the current+file’s directory. This can be useful for sharing common rules between+several rules files, eg:++# someaccount.csv.rules++## someaccount-specific rules+fields date,description,amount+account1 assets:someaccount+account2 expenses:misc++## common rules+include categorisation.rules+++File: hledger.info, Node: Working with CSV, Next: CSV rules examples, Prev: include, Up: CSV++11.17 Working with CSV+======================++Some tips:++* Menu:++* Rapid feedback::+* Valid CSV::+* File Extension::+* Reading CSV from standard input::+* Reading multiple CSV files::+* Valid transactions::+* Deduplicating importing::+* Setting amounts::+* Amount signs::+* Setting currency/commodity::+* Amount decimal places::+* Referencing other fields::+* How CSV rules are evaluated::+* Well factored rules::+++File: hledger.info, Node: Rapid feedback, Next: Valid CSV, Up: Working with CSV++11.17.1 Rapid feedback+----------------------++It’s a good idea to get rapid feedback while creating/troubleshooting+CSV rules. Here’s a good way, using entr from eradman.com/entrproject:++$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'++ A desc: query (eg) is used to select just one, or a few, transactions+of interest. "bash -c" is used to run multiple commands, so we can echo+a separator each time the command re-runs, making it easier to read the+output.+++File: hledger.info, Node: Valid CSV, Next: File Extension, Prev: Rapid feedback, Up: Working with CSV++11.17.2 Valid CSV+-----------------++Note that hledger will only accept valid CSV conforming to RFC 4180, and+equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab+as separators). This means, eg:++ • Values may be enclosed in double quotes, or not. Enclosing in+ single quotes is not allowed. (Eg ‘'A','B'’ is rejected.)+ • When values are enclosed in double quotes, spaces outside the+ quotes are not allowed. (Eg ‘"A", "B"’ is rejected.)+ • When values are not enclosed in quotes, they may not contain double+ quotes. (Eg ‘A"A, B’ is rejected.)++ If your CSV/SSV/TSV is not valid in this sense, you’ll need to+transform it before reading with hledger. Try using sed, or a more+permissive CSV parser like python’s csv lib.+++File: hledger.info, Node: File Extension, Next: Reading CSV from standard input, Prev: Valid CSV, Up: Working with CSV++11.17.3 File Extension+----------------------++To help hledger choose the CSV file reader and show the right error+messages (and choose the right field separator character by default),+it’s best if CSV/SSV/TSV files are named with a ‘.csv’, ‘.ssv’ or ‘.tsv’+filename extension. (More about this at Data formats.)++ When reading files with the "wrong" extension, you can ensure the CSV+reader (and the default field separator) by prefixing the file path with+‘csv:’, ‘ssv:’ or ‘tsv:’: Eg:++$ hledger -f ssv:foo.dat print++ You can also override the default field separator with a separator+rule if needed.+++File: hledger.info, Node: Reading CSV from standard input, Next: Reading multiple CSV files, Prev: File Extension, Up: Working with CSV++11.17.4 Reading CSV from standard input+---------------------------------------++You’ll need the file format prefix when reading CSV from stdin also,+since hledger assumes journal format by default. Eg:++$ cat foo.dat | hledger -f ssv:- print+++File: hledger.info, Node: Reading multiple CSV files, Next: Valid transactions, Prev: Reading CSV from standard input, Up: Working with CSV++11.17.5 Reading multiple CSV files+----------------------------------++If you use multiple ‘-f’ options to read multiple CSV files at once,+hledger will look for a correspondingly-named rules file for each CSV+file. But if you use the ‘--rules-file’ option, that rules file will be+used for all the CSV files.+++File: hledger.info, Node: Valid transactions, Next: Deduplicating importing, Prev: Reading multiple CSV files, Up: Working with CSV++11.17.6 Valid transactions+--------------------------++After reading a CSV file, hledger post-processes and validates the+generated journal entries as it would for a journal file - balancing+them, applying balance assignments, and canonicalising amount styles.+Any errors at this stage will be reported in the usual way, displaying+the problem entry.++ There is one exception: balance assertions, if you have generated+them, will not be checked, since normally these will work only when the+CSV data is part of the main journal. If you do need to check balance+assertions generated from CSV right away, pipe into another hledger:++$ hledger -f file.csv print | hledger -f- print+++File: hledger.info, Node: Deduplicating importing, Next: Setting amounts, Prev: Valid transactions, Up: Working with CSV++11.17.7 Deduplicating, importing+--------------------------------++When you download a CSV file periodically, eg to get your latest bank+transactions, the new file may overlap with the old one, containing some+of the same records.++ The import command will (a) detect the new transactions, and (b)+append just those transactions to your main journal. It is idempotent,+so you don’t have to remember how many times you ran it or with which+version of the CSV. (It keeps state in a hidden ‘.latest.FILE.csv’+file.) This is the easiest way to import CSV data. Eg:++# download the latest CSV files, then run this command.+# Note, no -f flags needed here.+$ hledger import *.csv [--dry]++ This method works for most CSV files. (Where records have a stable+chronological order, and new records appear only at the new end.)++ A number of other tools and workflows, hledger-specific and+otherwise, exist for converting, deduplicating, classifying and managing+CSV data. See:++ • https://hledger.org/cookbook.html#setups-and-workflows+ • https://plaintextaccounting.org -> data import/conversion+++File: hledger.info, Node: Setting amounts, Next: Amount signs, Prev: Deduplicating importing, Up: Working with CSV++11.17.8 Setting amounts+-----------------------++Continuing from amount field above, here are more tips on handling+various amount-setting situations:++ 1. *If the amount is in a single CSV field:*++ a. *If its sign indicates direction of flow:*+ Assign it to ‘amountN’, to set the Nth posting’s amount. N is+ usually 1 or 2 but can go up to 99.++ b. *If another field indicates direction of flow:*+ Use one or more conditional rules to set the appropriate+ amount sign. Eg:++ # assume a withdrawal unless Type contains "deposit":+ amount1 -%Amount+ if %Type deposit+ amount1 %Amount++ 2. *If the amount is in one of two CSV fields (eg Debit and Credit):*++ a. *If both fields are unsigned:*+ Assign the fields to ‘amountN-in’ and ‘amountN-out’. This+ sets posting N’s amount to whichever of these has a non-zero+ value. If it’s the -out value, the amount will be negated.++ b. *If either field is signed:*+ Use a conditional rule to flip the sign when needed. Eg+ below, the -out value already has a minus sign so we undo+ hledger’s automatic negating by negating once more (but only+ if the field is non-empty, so that we don’t leave a minus sign+ by itself):++ fields date, description, amount1-in, amount1-out+ if %amount1-out [1-9]+ amount1-out -%amount1-out++ c. *If both fields can contain a non-zero value (or both can be+ empty):*+ The -in/-out rules normally choose the value which is+ non-zero/non-empty. Some value pairs can be ambiguous, such+ as ‘1’ and ‘none’. For such cases, use conditional rules to+ help select the amount. Eg, to handle the above you could+ select the value containing non-zero digits:++ fields date, description, in, out+ if %in [1-9]+ amount1 %in+ if %out [1-9]+ amount1 %out++ 3. *If you want posting 2’s amount converted to cost:*+ Use the unnumbered ‘amount’ (or ‘amount-in’ and ‘amount-out’)+ syntax.++ 4. *If the CSV has only balance amounts, not transaction amounts:*+ Assign to ‘balanceN’, to set a balance assignment on the Nth+ posting, causing the posting’s amount to be calculated+ automatically. ‘balance’ with no number is equivalent to+ ‘balance1’. In this situation hledger is more likely to guess the+ wrong default account name, so you may need to set that explicitly.+++File: hledger.info, Node: Amount signs, Next: Setting currency/commodity, Prev: Setting amounts, Up: Working with CSV++11.17.9 Amount signs+--------------------++There is some special handling for amount signs, to simplify parsing and+sign-flipping:++ • *If an amount value begins with a plus sign:*+ that will be removed: ‘+AMT’ becomes ‘AMT’++ • *If an amount value is parenthesised:*+ it will be de-parenthesised and sign-flipped: ‘(AMT)’ becomes+ ‘-AMT’++ • *If an amount value has two minus signs (or two sets of+ parentheses, or a minus sign and parentheses):*+ they cancel out and will be removed: ‘--AMT’ or ‘-(AMT)’ becomes+ ‘AMT’++ • *If an amount value contains just a sign (or just a set of+ parentheses):*+ that is removed, making it an empty value. ‘"+"’ or ‘"-"’ or+ ‘"()"’ becomes ‘""’.+++File: hledger.info, Node: Setting currency/commodity, Next: Amount decimal places, Prev: Amount signs, Up: Working with CSV++11.17.10 Setting currency/commodity+-----------------------------------++If the currency/commodity symbol is included in the CSV’s amount+field(s):++2020-01-01,foo,$123.00++ you don’t have to do anything special for the commodity symbol, it+will be assigned as part of the amount. Eg:++fields date,description,amount++2020-01-01 foo+ expenses:unknown $123.00+ income:unknown $-123.00++ If the currency is provided as a separate CSV field:++2020-01-01,foo,USD,123.00++ You can assign that to the ‘currency’ pseudo-field, which has the+special effect of prepending itself to every amount in the transaction+(on the left, with no separating space):++fields date,description,currency,amount++2020-01-01 foo+ expenses:unknown USD123.00+ income:unknown USD-123.00++ Or, you can use a field assignment to construct the amount yourself,+with more control. Eg to put the symbol on the right, and separated by+a space:++fields date,description,cur,amt+amount %amt %cur++2020-01-01 foo+ expenses:unknown 123.00 USD+ income:unknown -123.00 USD++ Note we used a temporary field name (‘cur’) that is not ‘currency’ -+that would trigger the prepending effect, which we don’t want here.+++File: hledger.info, Node: Amount decimal places, Next: Referencing other fields, Prev: Setting currency/commodity, Up: Working with CSV++11.17.11 Amount decimal places+------------------------------++Like amounts in a journal file, the amounts generated by CSV rules like+‘amount1’ influence commodity display styles, such as the number of+decimal places displayed in reports.++ The original amounts as written in the CSV file do not affect display+style (because we don’t yet reliably know their commodity).+++File: hledger.info, Node: Referencing other fields, Next: How CSV rules are evaluated, Prev: Amount decimal places, Up: Working with CSV++11.17.12 Referencing other fields+---------------------------------++In field assignments, you can interpolate only CSV fields, not hledger+fields. In the example below, there’s both a CSV field and a hledger+field named amount1, but %amount1 always means the CSV field, not the+hledger field:++# Name the third CSV field "amount1"+fields date,description,amount1++# Set hledger's amount1 to the CSV amount1 field followed by USD+amount1 %amount1 USD++# Set comment to the CSV amount1 (not the amount1 assigned above)+comment %amount1++ Here, since there’s no CSV amount1 field, %amount1 will produce a+literal "amount1":++fields date,description,csvamount+amount1 %csvamount USD+# Can't interpolate amount1 here+comment %amount1++ When there are multiple field assignments to the same hledger field,+only the last one takes effect. Here, comment’s value will be be B, or+C if "something" is matched, but never A:++comment A+comment B+if something+ comment C+++File: hledger.info, Node: How CSV rules are evaluated, Next: Well factored rules, Prev: Referencing other fields, Up: Working with CSV++11.17.13 How CSV rules are evaluated+------------------------------------++Here’s how to think of CSV rules being evaluated (if you really need+to). First,++ • ‘include’ - all includes are inlined, from top to bottom, depth+ first. (At each include point the file is inlined and scanned for+ further includes, recursively, before proceeding.)++ Then "global" rules are evaluated, top to bottom. If a rule is+repeated, the last one wins:++ • ‘skip’ (at top level)+ • ‘date-format’+ • ‘newest-first’+ • ‘fields’ - names the CSV fields, optionally sets up initial+ assignments to hledger fields++ Then for each CSV record in turn:++ • test all ‘if’ blocks. If any of them contain a ‘end’ rule, skip+ all remaining CSV records. Otherwise if any of them contain a+ ‘skip’ rule, skip that many CSV records. If there are multiple+ matched ‘skip’ rules, the first one wins.+ • collect all field assignments at top level and in matched ‘if’+ blocks. When there are multiple assignments for a field, keep only+ the last one.+ • compute a value for each hledger field - either the one that was+ assigned to it (and interpolate the %CSVFIELD references), or a+ default+ • generate a hledger transaction (journal entry) from these values.++ This is all part of the CSV reader, one of several readers hledger+can use to parse input files. When all files have been read+successfully, the transactions are passed as input to whichever hledger+command the user specified.+++File: hledger.info, Node: Well factored rules, Prev: How CSV rules are evaluated, Up: Working with CSV++11.17.14 Well factored rules+----------------------------++Some things than can help reduce duplication and complexity in rules+files:++ • Extracting common rules usable with multiple CSV files into a+ ‘common.rules’, and adding ‘include common.rules’ to each CSV’s+ rules file.++ • Splitting if blocks into smaller if blocks, extracting the+ frequently used parts.+++File: hledger.info, Node: CSV rules examples, Prev: Working with CSV, Up: CSV++11.18 CSV rules examples+========================++* Menu:++* Bank of Ireland::+* Coinbase::+* Amazon::+* Paypal::+++File: hledger.info, Node: Bank of Ireland, Next: Coinbase, Up: CSV rules examples++11.18.1 Bank of Ireland+-----------------------++Here’s a CSV with two amount fields (Debit and Credit), and a balance+field, which we can use to add balance assertions, which is not+necessary but provides extra error checking:++Date,Details,Debit,Credit,Balance+07/12/2012,LODGMENT 529898,,10.0,131.21+07/12/2012,PAYMENT,5,,126++# bankofireland-checking.csv.rules++# skip the header line+skip++# name the csv fields, and assign some of them as journal entry fields+fields date, description, amount-out, amount-in, balance++# We generate balance assertions by assigning to "balance"+# above, but you may sometimes need to remove these because:+#+# - the CSV balance differs from the true balance,+# by up to 0.0000000000005 in my experience+#+# - it is sometimes calculated based on non-chronological ordering,+# eg when multiple transactions clear on the same day++# date is in UK/Ireland format+date-format %d/%m/%Y++# set the currency+currency EUR++# set the base account for all txns+account1 assets:bank:boi:checking++$ hledger -f bankofireland-checking.csv print+2012-12-07 LODGMENT 529898+ assets:bank:boi:checking EUR10.0 = EUR131.2+ income:unknown EUR-10.0++2012-12-07 PAYMENT+ assets:bank:boi:checking EUR-5.0 = EUR126.0+ expenses:unknown EUR5.0++ The balance assertions don’t raise an error above, because we’re+reading directly from CSV, but they will be checked if these entries are+imported into a journal file.+++File: hledger.info, Node: Coinbase, Next: Amazon, Prev: Bank of Ireland, Up: CSV rules examples++11.18.2 Coinbase+----------------++A simple example with some CSV from Coinbase. The spot price is+recorded using cost notation. The legacy ‘amount’ field name+conveniently sets amount 2 (posting 2’s amount) to the total cost.++# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes+# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"++# coinbase.csv.rules+skip 1+fields Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes+date %Timestamp+date-format %Y-%m-%dT%T%Z+description %Notes+account1 assets:coinbase:cc+amount %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency++$ hledger print -f coinbase.csv+2021-12-30 Received 100.00 USDC from an external account+ assets:coinbase:cc 100 USDC @ 0.740000 GBP+ income:unknown -74.000000 GBP+++File: hledger.info, Node: Amazon, Next: Paypal, Prev: Coinbase, Up: CSV rules examples++11.18.3 Amazon+--------------++Here we convert amazon.com order history, and use an if block to+generate a third posting if there’s a fee. (In practice you’d probably+get this data from your bank instead, but it’s an example.)++"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"+"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"+"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"++# amazon-orders.csv.rules++# skip one header line+skip 1++# name the csv fields, and assign the transaction's date, amount and code.+# Avoided the "status" and "amount" hledger field names to prevent confusion.+fields date, _, toorfrom, name, amzstatus, amzamount, fees, code++# how to parse the date+date-format %b %-d, %Y++# combine two fields to make the description+description %toorfrom %name++# save the status as a tag+comment status:%amzstatus++# set the base account for all transactions+account1 assets:amazon+# leave amount1 blank so it can balance the other(s).+# I'm assuming amzamount excludes the fees, don't remember++# set a generic account2+account2 expenses:misc+amount2 %amzamount+# and maybe refine it further:+#include categorisation.rules++# add a third posting for fees, but only if they are non-zero.+if %fees [1-9]+ account3 expenses:fees+ amount3 %fees++$ hledger -f amazon-orders.csv print+2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo. ; status:Completed+ assets:amazon+ expenses:misc $20.00++2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc. ; status:Completed+ assets:amazon+ expenses:misc $25.00+ expenses:fees $1.00+++File: hledger.info, Node: Paypal, Prev: Amazon, Up: CSV rules examples++11.18.4 Paypal+--------------++Here’s a real-world rules file for (customised) Paypal CSV, with some+Paypal-specific rules, and a second rules file included:++"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"+"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""+"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""+"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""+"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""+"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""+"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""+"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""++# paypal-custom.csv.rules++# Tips:+# Export from Activity -> Statements -> Custom -> Activity download+# Suggested transaction type: "Balance affecting"+# Paypal's default fields in 2018 were:+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"+# This rules file assumes the following more detailed fields, configured in "Customize report fields":+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"++fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note++skip 1++date-format %-m/%-d/%Y++# ignore some paypal events+if+In Progress+Temporary Hold+Update to+ skip++# add more fields to the description+description %description_ %itemtitle++# save some other fields as tags+comment itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_++# convert to short currency symbols+if %currency USD+ currency $+if %currency EUR+ currency E+if %currency GBP+ currency P++# generate postings++# the first posting will be the money leaving/entering my paypal account+# (negative means leaving my account, in all amount fields)+account1 assets:online:paypal+amount1 %netamount++# the second posting will be money sent to/received from other party+# (account2 is set below)+amount2 -%grossamount++# if there's a fee, add a third posting for the money taken by paypal.+if %feeamount [1-9]+ account3 expenses:banking:paypal+ amount3 -%feeamount+ comment3 business:++# choose an account for the second posting++# override the default account names:+# if the amount is positive, it's income (a debit)+if %grossamount ^[^-]+ account2 income:unknown+# if negative, it's an expense (a credit)+if %grossamount ^-+ account2 expenses:unknown++# apply common rules for setting account2 & other tweaks+include common.rules++# apply some overrides specific to this csv++# Transfers from/to bank. These are usually marked Pending,+# which can be disregarded in this case.+if+Bank Account+Bank Deposit to PP Account+ description %type for %referencetxnid %itemtitle+ account2 assets:bank:wf:pchecking+ account1 assets:online:paypal++# Currency conversions+if Currency Conversion+ account2 equity:currency conversion++# common.rules++if+darcs+noble benefactor+ account2 revenues:foss donations:darcshub+ comment2 business:++if+Calm Radio+ account2 expenses:online:apps++if+electronic frontier foundation+Patreon+wikimedia+Advent of Code+ account2 expenses:dues++if Google+ account2 expenses:online:apps+ description google | music++$ hledger -f paypal-custom.csv print+2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed+ assets:online:paypal $-6.99 = $-6.99+ expenses:online:apps $6.99++2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $6.99 = $0.00+ assets:bank:wf:pchecking $-6.99++2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed+ assets:online:paypal $-7.00 = $-7.00+ expenses:dues $7.00++2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $7.00 = $0.00+ assets:bank:wf:pchecking $-7.00++2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed+ assets:online:paypal $-2.00 = $-2.00+ expenses:dues $2.00+ expenses:banking:paypal ; business:++2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending+ assets:online:paypal $2.00 = $0.00+ assets:bank:wf:pchecking $-2.00++2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed+ assets:online:paypal $9.41 = $9.41+ revenues:foss donations:darcshub $-10.00 ; business:+ expenses:banking:paypal $0.59 ; business:+++File: hledger.info, Node: Timeclock, Next: Timedot, Prev: CSV, Up: Top++12 Timeclock+************++The time logging format of timeclock.el, as read by hledger.++ hledger can read time logs in timeclock format. As with Ledger,+these are (a subset of) timeclock.el’s format, containing clock-in and+clock-out entries as in the example below. The date is a simple date.+The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are+optional. The timezone, if present, must be four digits and is ignored+(currently the time is always interpreted as a local time). Lines+beginning with ‘#’ or ‘;’ or ‘*’, and blank lines, are ignored.++i 2015/03/30 09:00:00 some:account name optional description after two spaces+o 2015/03/30 09:20:00+i 2015/03/31 22:21:45 another account+o 2015/04/01 02:00:34++ hledger treats each clock-in/clock-out pair as a transaction posting+some number of hours to an account. Or if the session spans more than+one day, it is split into several transactions, one for each day. For+the above time log, ‘hledger print’ generates these journal entries:++$ hledger -f t.timeclock print+2015-03-30 * optional description after two spaces+ (some:account name) 0.33h++2015-03-31 * 22:21-23:59+ (another account) 1.64h++2015-04-01 * 00:00-02:00+ (another account) 2.01h++ Here is a sample.timeclock to download and some queries to try:++$ hledger -f sample.timeclock balance # current time balances+$ hledger -f sample.timeclock register -p 2009/3 # sessions in march 2009+$ hledger -f sample.timeclock register -p weekly --depth 1 --empty # time summary by week++ To generate time logs, ie to clock in and clock out, you could:++ • use emacs and the built-in timeclock.el, or the extended+ timeclock-x.el and perhaps the extras in ledgerutils.el++ • at the command line, use these bash aliases: ‘shell alias ti="echo+ i `date '+%Y-%m-%d %H:%M:%S'` \$* >>$TIMELOG" alias to="echo o+ `date '+%Y-%m-%d %H:%M:%S'` >>$TIMELOG"’++ • or use the old ‘ti’ and ‘to’ scripts in the ledger 2.x repository.+ These rely on a "timeclock" executable which I think is just the+ ledger 2 executable renamed.+++File: hledger.info, Node: Timedot, Next: PART 3 REPORTING CONCEPTS, Prev: Timeclock, Up: Top++13 Timedot+**********++‘timedot’ format is hledger’s human-friendly time logging format.+Compared to ‘timeclock’ format, it is++ • convenient for quick, approximate, and retroactive time logging+ • readable: you can see at a glance where time was spent.++ A timedot file contains a series of day entries, which might look+like this:++2021-08-04+hom:errands .... ....+fos:hledger:timedot .. ; docs+per:admin:finance ++ hledger reads this as three time transactions on this day, with each+dot representing a quarter-hour spent:++$ hledger -f a.timedot print # .timedot file extension activates the timedot reader+2021-08-04 *+ (hom:errands) 2.00++2021-08-04 *+ (fos:hledger:timedot) 0.50++2021-08-04 *+ (per:admin:finance) 0++ A day entry begins with a date line:++ • a non-indented *simple date* (Y-M-D, Y/M/D, or Y.M.D).++ Optionally this can be followed on the same line by++ • a common *transaction description* for this day+ • a common *transaction comment* for this day, after a semicolon+ (‘;’).++ After the date line are zero or more optionally-indented time+transaction lines, consisting of:++ • an *account name* - any word or phrase, usually a hledger-style+ account name.+ • *two or more spaces* - a field separator, required if there is an+ amount (as in journal format).+ • a *timedot amount* - dots representing quarter hours, or a number+ representing hours.+ • an optional *comment* beginning with semicolon. This is ignored.++ In more detail, timedot amounts can be:++ • *dots*: zero or more period characters, each representing one+ quarter-hour. Spaces are ignored and can be used for grouping.+ Eg: ‘.... ..’++ • a *number*, representing hours. Eg: ‘1.5’++ • a *number immediately followed by a unit symbol* ‘s’, ‘m’, ‘h’,+ ‘d’, ‘w’, ‘mo’, or ‘y’, representing seconds, minutes, hours, days+ weeks, months or years. Eg ‘1.5h’ or ‘90m’. The following+ equivalencies are assumed:+ ‘60s’ = ‘1m’, ‘60m’ = ‘1h’, ‘24h’ = ‘1d’, ‘7d’ = ‘1w’, ‘30d’ =+ ‘1mo’, ‘365d’ = ‘1y’. (This unit will not be visible in the+ generated transaction amount, which is always in hours.)++ There is some added flexibility to help with keeping time log data in+the same file as your notes, todo lists, etc.:++ • Blank lines and lines beginning with ‘#’ or ‘;’ are ignored.++ • Before the first date line, lines beginning with ‘*’ are ignored.+ From the first date line onward, a sequence of ‘*’’s followed by a+ space at beginning of lines (ie, the headline prefix used by Emacs+ Org mode) is ignored. This means the time log can be kept under an+ Org headline, and date lines or time transaction lines can be Org+ headlines.++ • Lines not ending with a double-space and amount are parsed as+ transactions with zero amount. (Most hledger reports hide these by+ default; add -E to see them.)++ More examples:++# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.+2016/2/1+inc:client1 .... .... .... .... .... ....+fos:haskell .... ..+biz:research .++2016/2/2+inc:client1 .... ....+biz:research .++2016/2/3+inc:client1 4+fos:hledger 3+biz:research 1++* Time log+** 2020-01-01+*** adm:time .+*** adm:finance .++* 2020 Work Diary+** Q1+*** 2020-02-29+**** DONE+0700 yoga+**** UNPLANNED+**** BEGUN+hom:chores+ cleaning ...+ water plants+ outdoor - one full watering can+ indoor - light watering+**** TODO+adm:planning: trip+*** LATER++ Reporting:++$ hledger -f a.timedot print date:2016/2/2+2016-02-02 *+ (inc:client1) 2.00++2016-02-02 *+ (biz:research) 0.25++$ hledger -f a.timedot bal --daily --tree+Balance changes in 2016-02-01-2016-02-03:++ || 2016-02-01d 2016-02-02d 2016-02-03d +============++========================================+ biz || 0.25 0.25 1.00 + research || 0.25 0.25 1.00 + fos || 1.50 0 3.00 + haskell || 1.50 0 0 + hledger || 0 0 3.00 + inc || 6.00 2.00 4.00 + client1 || 6.00 2.00 4.00 +------------++----------------------------------------+ || 7.75 2.25 8.00 ++ Using period instead of colon as account name separator:++2016/2/4+fos.hledger.timedot 4+fos.ledger ..++$ hledger -f a.timedot --alias /\\./=: bal --tree+ 4.50 fos+ 4.00 hledger:timedot+ 0.50 ledger+--------------------+ 4.50++ A sample.timedot file.+++File: hledger.info, Node: PART 3 REPORTING CONCEPTS, Next: Time periods, Prev: Timedot, Up: Top++14 PART 3: REPORTING CONCEPTS+*****************************+++File: hledger.info, Node: Time periods, Next: Depth, Prev: PART 3 REPORTING CONCEPTS, Up: Top++15 Time periods+***************++* Menu:++* Report start & end date::+* Smart dates::+* Report intervals::+* Date adjustment::+* Period expressions::+++File: hledger.info, Node: Report start & end date, Next: Smart dates, Up: Time periods++15.1 Report start & end date+============================++By default, most hledger reports will show the full span of time+represented by the journal. The report start date will be the earliest+transaction or posting date, and the report end date will be the latest+transaction, posting, or market price date.++ Often you will want to see a shorter time span, such as the current+month. You can specify a start and/or end date using ‘-b/--begin’,+‘-e/--end’, ‘-p/--period’ or a ‘date:’ query (described below). All of+these accept the smart date syntax (below).++ Some notes:++ • End dates are exclusive, as in Ledger, so you should write the date+ _after_ the last day you want to see in the report.+ • As noted in reporting options: among start/end dates specified with+ _options_, the last (i.e. right-most) option takes precedence.+ • The effective report start and end dates are the intersection of+ the start/end dates from options and that from ‘date:’ queries.+ That is, ‘date:2019-01 date:2019 -p'2000 to 2030'’ yields January+ 2019, the smallest common time span.+ • In some cases a report interval will adjust start/end dates to fall+ on interval boundaries (see below).++ Examples:++‘-b begin on St. Patrick’s day 2016+2016/3/17’+‘-e 12/1’ end at the start of december 1st of the current year+ (11/30 will be the last date included)+‘-b all transactions on or after the 1st of the current month+thismonth’+‘-p all transactions in the current month+thismonth’+‘date:2016/3/17..’the above written as queries instead (‘..’ can also be+ replaced with ‘-’)+‘date:..12/1’+‘date:thismonth..’+‘date:thismonth’+++File: hledger.info, Node: Smart dates, Next: Report intervals, Prev: Report start & end date, Up: Time periods++15.2 Smart dates+================++hledger’s user interfaces accept a "smart date" syntax for added+convenience. Smart dates optionally can be relative to today’s date, be+written with english words, and have less-significant parts omitted+(missing parts are inferred as 1). Some examples:++‘2004/10/1’, exact date, several separators allowed. Year+‘2004-01-01’, is 4+ digits, month is 1-12, day is 1-31+‘2004.9.1’+‘2004’ start of year+‘2004/10’ start of month+‘10/1’ month and day in current year+‘21’ day in current month+‘october, oct’ start of month in current year+‘yesterday, today, -1, 0, 1 days from today+tomorrow’+‘last/this/next -1, 0, 1 periods from the current period+day/week/month/quarter/year’+‘in n n periods from the current period+days/weeks/months/quarters/years’+‘n n periods from the current period+days/weeks/months/quarters/years+ahead’+‘n -n periods from the current period+days/weeks/months/quarters/years+ago’+‘20181201’ 8 digit YYYYMMDD with valid year month and+ day+‘201812’ 6 digit YYYYMM with valid year and month++ Some counterexamples - malformed digit sequences might give+surprising results:++‘201813’ 6 digits with an invalid month is parsed as start of+ 6-digit year+‘20181301’ 8 digits with an invalid month is parsed as start of+ 8-digit year+‘20181232’ 8 digits with an invalid day gives an error+‘201801012’ 9+ digits beginning with a valid YYYYMMDD gives an error++ "Today’s date" can be overridden with the ‘--today’ option, in case+it’s needed for testing or for recreating old reports. (Except for+periodic transaction rules, which are not affected by ‘--today’.)+++File: hledger.info, Node: Report intervals, Next: Date adjustment, Prev: Smart dates, Up: Time periods++15.3 Report intervals+=====================++A report interval can be specified so that reports like register,+balance or activity become multi-period, showing each subperiod as a+separate row or column.++ The following standard intervals can be enabled with command-line+flags:++ • ‘-D/--daily’+ • ‘-W/--weekly’+ • ‘-M/--monthly’+ • ‘-Q/--quarterly’+ • ‘-Y/--yearly’++ More complex intervals can be specified using ‘-p/--period’,+described below.+++File: hledger.info, Node: Date adjustment, Next: Period expressions, Prev: Report intervals, Up: Time periods++15.4 Date adjustment+====================++With a report interval (other than daily), report start / end dates+which have not been specified explicitly and in full (eg not ‘-b+2023-01-01’, but ‘-b 2023-01’ or ‘-b 2023’ or unspecified) are+considered flexible:++ • A flexible start date will be automatically adjusted earlier if+ needed to fall on a natural interval boundary.+ • Similarly, a flexible end date will be adjusted later if needed to+ make the last period a whole interval (the same length as the+ others).++ This is convenient for producing clean periodic reports (this is+traditional hledger behaviour). By contrast, fully-specified exact+dates will not be adjusted (this is new in hledger 1.29).++ An example: with a journal whose first date is 2023-01-10 and last+date is 2023-03-20:++ • ‘hledger bal -M -b 2023/1/15 -e 2023/3/10’+ The report periods will begin on the 15th day of each month,+ starting from 2023-01-15, and the last period’s last day will be+ 2023-03-09. (Exact start and end dates, neither is adjusted.)++ • ‘hledger bal -M -b 2023-01 -e 2023-04’ or ‘hledger bal -M’+ The report periods will begin on the 1st of each month, starting+ from 2023-01-01, and the last period’s last day will be 2023-03-31.+ (Flexible start and end dates, both are adjusted.)+++File: hledger.info, Node: Period expressions, Prev: Date adjustment, Up: Time periods++15.5 Period expressions+=======================++The ‘-p/--period’ option specifies a period expression, which is a+compact way of expressing a start date, end date, and/or report+interval.++ Here’s a period expression with a start and end date (specifying the+first quarter of 2009):++‘-p "from 2009/1/1 to 2009/4/1"’++ Several keywords like "from" and "to" are supported for readability;+these are optional. "to" can also be written as ".." or "-". The+spaces are also optional, as long as you don’t run two dates together.+So the following are equivalent to the above:++‘-p "2009/1/1 2009/4/1"’+‘-p2009/1/1to2009/4/1’+‘-p2009/1/1..2009/4/1’++ Dates are smart dates, so if the current year is 2009, these are also+equivalent to the above:++‘-p "1/1 4/1"’+‘-p "jan-apr"’+‘-p "this year to 4/1"’++ If you specify only one date, the missing start or end date will be+the earliest or latest transaction date in the journal:++‘-p "from 2009/1/1"’ everything after january 1, 2009+‘-p "since 2009/1"’ the same, since is a synonym+‘-p "from 2009"’ the same+‘-p "to 2009"’ everything before january 1, 2009++ You can also specify a period by writing a single partial or full+date:++‘-p "2009"’ the year 2009; equivalent to “2009/1/1 to 2010/1/1”+‘-p "2009/1"’ the month of january 2009; equivalent to “2009/1/1 to+ 2009/2/1”+‘-p the first day of 2009; equivalent to “2009/1/1 to+"2009/1/1"’ 2009/1/2”++ or by using the "Q" quarter-year syntax (case insensitive):++‘-p "2009Q1"’ first quarter of 2009, equivalent to “2009/1/1 to+ 2009/4/1”+‘-p "q4"’ fourth quarter of the current year++* Menu:++* Period expressions with a report interval::+* More complex report intervals::+* Multiple weekday intervals::+++File: hledger.info, Node: Period expressions with a report interval, Next: More complex report intervals, Up: Period expressions++15.5.1 Period expressions with a report interval+------------------------------------------------++A period expression can also begin with a report interval, separated+from the start/end dates (if any) by a space or the word ‘in’:++‘-p "weekly from 2009/1/1 to 2009/4/1"’+‘-p "monthly in 2008"’+‘-p "quarterly"’+++File: hledger.info, Node: More complex report intervals, Next: Multiple weekday intervals, Prev: Period expressions with a report interval, Up: Period expressions++15.5.2 More complex report intervals+------------------------------------++Some more complex intervals can be specified within period expressions,+such as:++ • ‘biweekly’ (every two weeks)+ • ‘fortnightly’+ • ‘bimonthly’ (every two months)+ • ‘every day|week|month|quarter|year’+ • ‘every N days|weeks|months|quarters|years’++ Weekly on a custom day:++ • ‘every Nth day of week’ (‘th’, ‘nd’, ‘rd’, or ‘st’ are all accepted+ after the number)+ • ‘every WEEKDAYNAME’ (full or three-letter english weekday name,+ case insensitive)++ Monthly on a custom day:++ • ‘every Nth day [of month]’+ • ‘every Nth WEEKDAYNAME [of month]’++ Yearly on a custom day:++ • ‘every MM/DD [of year]’ (month number and day of month number)+ • ‘every MONTHNAME DDth [of year]’ (full or three-letter english+ month name, case insensitive, and day of month number)+ • ‘every DDth MONTHNAME [of year]’ (equivalent to the above)++ Examples:++‘-p "bimonthly from+2008"’+‘-p "every 2 weeks"’+‘-p "every 5 months from+2009/03"’+‘-p "every 2nd day of periods will go from Tue to Tue+week"’+‘-p "every Tue"’ same+‘-p "every 15th day"’ period boundaries will be on 15th of each+ month+‘-p "every 2nd Monday"’ period boundaries will be on second Monday+ of each month+‘-p "every 11/05"’ yearly periods with boundaries on 5th of+ November+‘-p "every 5th November"’ same+‘-p "every Nov 5th"’ same++ Show historical balances at end of the 15th day of each month (N is+an end date, exclusive as always):++$ hledger balance -H -p "every 16th day"++ Group postings from the start of wednesday to end of the following+tuesday (N is both (inclusive) start date and (exclusive) end date):++$ hledger register checking -p "every 3rd day of week"+++File: hledger.info, Node: Multiple weekday intervals, Prev: More complex report intervals, Up: Period expressions++15.5.3 Multiple weekday intervals+---------------------------------++This special form is also supported:++ • ‘every WEEKDAYNAME,WEEKDAYNAME,...’ (full or three-letter english+ weekday names, case insensitive)++ Also, ‘weekday’ and ‘weekendday’ are shorthand for+‘mon,tue,wed,thu,fri’ and ‘sat,sun’.++ This is mainly intended for use with ‘--forecast’, to generate+periodic transactions on arbitrary days of the week. It may be less+useful with ‘-p’, since it divides each week into subperiods of unequal+length, which is unusual. (Related: #1632)++ Examples:++‘-p "every dates will be Mon, Wed, Fri; periods will be+mon,wed,fri"’ Mon-Tue, Wed-Thu, Fri-Sun+‘-p "every dates will be Mon, Tue, Wed, Thu, Fri; periods will+weekday"’ be Mon, Tue, Wed, Thu, Fri-Sun+‘-p "every dates will be Sat, Sun; periods will be Sat, Sun-Fri+weekendday"’+++File: hledger.info, Node: Depth, Next: Queries, Prev: Time periods, Up: Top++16 Depth+********++With the ‘--depth NUM’ option (short form: ‘-NUM’), reports will show+accounts only to the specified depth, hiding deeper subaccounts. Use+this when you want a summary with less detail. This flag has the same+effect as a ‘depth:’ query argument: ‘depth:2’, ‘--depth=2’ or ‘-2’ are+equivalent.+++File: hledger.info, Node: Queries, Next: Pivoting, Prev: Depth, Up: Top++17 Queries+**********++One of hledger’s strengths is being able to quickly report on a precise+subset of your data. Most hledger commands accept optional query+arguments to restrict their scope. The syntax is as follows:++ • Zero or more space-separated query terms. These are most often+ account name substrings:++ ‘utilities food:groceries’++ • Terms with spaces or other special characters should be enclosed in+ quotes:++ ‘"personal care"’++ • Regular expressions are also supported:++ ‘"^expenses\b" "accounts (payable|receivable)"’++ • Add a query type prefix to match other parts of the data:++ ‘date:202012- desc:amazon cur:USD amt:">100" status:’++ • Add a ‘not:’ prefix to negate a term:++ ‘not:cur:USD’++* Menu:++* Query types::+* Combining query terms::+* Queries and command options::+* Queries and valuation::+* Querying with account aliases::+* Querying with cost or value::+++File: hledger.info, Node: Query types, Next: Combining query terms, Up: Queries++17.1 Query types+================++Here are the types of query term available. Remember these can also be+prefixed with *‘not:’* to convert them into a negative match.++ *‘acct:REGEX’, ‘REGEX’*+Match account names containing this (case insensitive) regular+expression. This is the default query type when there is no prefix, and+regular expression syntax is typically not needed, so usually we just+write an account name substring, like ‘expenses’ or ‘food’.++ *‘amt:N, amt:<N, amt:<=N, amt:>N, amt:>=N’*+Match postings with a single-commodity amount equal to, less than, or+greater than N. (Postings with multi-commodity amounts are not tested+and will always match.) The comparison has two modes: if N is preceded+by a + or - sign (or is 0), the two signed numbers are compared.+Otherwise, the absolute magnitudes are compared, ignoring sign.++ *‘code:REGEX’*+Match by transaction code (eg check number).++ *‘cur:REGEX’*+Match postings or transactions including any amounts whose+currency/commodity symbol is fully matched by REGEX. (For a partial+match, use ‘.*REGEX.*’). Note, to match special characters which are+regex-significant, you need to escape them with ‘\’. And for characters+which are significant to your shell you may need one more level of+escaping. So eg to match the dollar sign:+‘hledger print cur:\\$’.++ *‘desc:REGEX’*+Match transaction descriptions.++ *‘date:PERIODEXPR’*+Match dates (or with the ‘--date2’ flag, secondary dates) within the+specified period. PERIODEXPR is a period expression with no report+interval. Examples:+‘date:2016’, ‘date:thismonth’, ‘date:2/1-2/15’,+‘date:2021-07-27..nextquarter’.++ *‘date2:PERIODEXPR’*+Match secondary dates within the specified period (independent of the+‘--date2’ flag).++ *‘depth:N’*+Match (or display, depending on command) accounts at or above this+depth.++ *‘note:REGEX’*+Match transaction notes (the part of the description right of ‘|’, or+the whole description if there’s no ‘|’).++ *‘payee:REGEX’*+Match transaction payee/payer names (the part of the description left of+‘|’, or the whole description if there’s no ‘|’).++ *‘real:, real:0’*+Match real or virtual postings respectively.++ *‘status:, status:!, status:*’*+Match unmarked, pending, or cleared transactions respectively.++ *‘type:TYPECODES’*+Match by account type (see Declaring accounts > Account types).+‘TYPECODES’ is one or more of the single-letter account type codes+‘ALERXCV’, case insensitive. Note ‘type:A’ and ‘type:E’ will also match+their respective subtypes ‘C’ (Cash) and ‘V’ (Conversion). Certain+kinds of account alias can disrupt account types, see Rewriting accounts+> Aliases and account types.++ *‘tag:REGEX[=REGEX]’*+Match by tag name, and optionally also by tag value. (To match only by+value, use ‘tag:.=REGEX’.)++ When querying by tag, note that:++ • Accounts also inherit the tags of their parent accounts+ • Postings also inherit the tags of their account and their+ transaction+ • Transactions also acquire the tags of their postings.++ (*‘inacct:ACCTNAME’*+A special query term used automatically in hledger-web only: tells+hledger-web to show the transaction register for an account.)+++File: hledger.info, Node: Combining query terms, Next: Queries and command options, Prev: Query types, Up: Queries++17.2 Combining query terms+==========================++When given multiple query terms, most commands select things which+match:++ • any of the description terms AND+ • any of the account terms AND+ • any of the status terms AND+ • all the other terms.++ The print command is a little different, showing transactions which:++ • match any of the description terms AND+ • have any postings matching any of the positive account terms AND+ • have no postings matching any of the negative account terms AND+ • match all the other terms.++ Although these fixed rules are enough for many needs, we do not+support full boolean expressions (#203), (and you should not write AND+or OR in your queries). This makes certain queries hard to express, but+here are some tricks that can help:++ 1. Use a doubled ‘not:’ prefix. Eg, to print only the food expenses+ paid with cash:++ $ hledger print food not:not:cash++ 2. Or pre-filter the transactions with ‘print’, piping the result into+ a second hledger command (with balance assertions disabled):++ $ hledger print cash | hledger -f- -I balance food+++File: hledger.info, Node: Queries and command options, Next: Queries and valuation, Prev: Combining query terms, Up: Queries++17.3 Queries and command options+================================++Some queries can also be expressed as command-line options: ‘depth:2’ is+equivalent to ‘--depth 2’, ‘date:2020’ is equivalent to ‘-p 2020’, etc.+When you mix command options and query arguments, generally the+resulting query is their intersection.+++File: hledger.info, Node: Queries and valuation, Next: Querying with account aliases, Prev: Queries and command options, Up: Queries++17.4 Queries and valuation+==========================++When amounts are converted to other commodities in cost or value+reports, ‘cur:’ and ‘amt:’ match the old commodity symbol and the old+amount quantity, not the new ones (except in hledger 1.22.0 where it’s+reversed, see #1625).+++File: hledger.info, Node: Querying with account aliases, Next: Querying with cost or value, Prev: Queries and valuation, Up: Queries++17.5 Querying with account aliases+==================================++When account names are rewritten with ‘--alias’ or ‘alias’, note that+‘acct:’ will match either the old or the new account name.+++File: hledger.info, Node: Querying with cost or value, Prev: Querying with account aliases, Up: Queries++17.6 Querying with cost or value+================================++When amounts are converted to other commodities in cost or value+reports, note that ‘cur:’ matches the new commodity symbol, and not the+old one, and ‘amt:’ matches the new quantity, and not the old one.+Note: this changed in hledger 1.22, previously it was the reverse, see+the discussion at #1625.+++File: hledger.info, Node: Pivoting, Next: Generating data, Prev: Queries, Up: Top++18 Pivoting+***********++Normally, hledger groups and sums amounts within each account. The+‘--pivot FIELD’ option substitutes some other transaction field for+account names, causing amounts to be grouped and summed by that field’s+value instead. FIELD can be any of the transaction fields ‘status’,+‘code’, ‘description’, ‘payee’, ‘note’, or a tag name. When pivoting on+a tag and a posting has multiple values of that tag, only the first+value is displayed. Values containing ‘colon:separated:parts’ will be+displayed hierarchically, like account names.++ Some examples:++2016/02/16 Yearly Dues Payment+ assets:bank account 2 EUR+ income:dues -2 EUR ; member: John Doe++ Normal balance report showing account names:++$ hledger balance+ 2 EUR assets:bank account+ -2 EUR income:dues+--------------------+ 0++ Pivoted balance report, using member: tag values instead:++$ hledger balance --pivot member+ 2 EUR+ -2 EUR John Doe+--------------------+ 0++ One way to show only amounts with a member: value (using a query):++$ hledger balance --pivot member tag:member=.+ -2 EUR John Doe+--------------------+ -2 EUR++ Another way (the acct: query matches against the pivoted "account+name"):++$ hledger balance --pivot member acct:.+ -2 EUR John Doe+--------------------+ -2 EUR+++File: hledger.info, Node: Generating data, Next: Forecasting, Prev: Pivoting, Up: Top++19 Generating data+******************++Two features for generating transient data (visible only at report time)+are built in to hledger’s journal format:++ • Auto posting rules can generate extra postings on certain+ transactions. They are activated by the ‘--auto’ flag.++ • Periodic transaction rules can generate repeating transactions,+ usually dated in the future, to help with forecasting or budgeting.+ They are activated by the ‘--forecast’ or ‘balance --budget’+ options, described next.+++File: hledger.info, Node: Forecasting, Next: Budgeting, Prev: Generating data, Up: Top++20 Forecasting+**************++The ‘--forecast’ flag activates any periodic transaction rules in the+journal. These will generate temporary additional transactions, usually+recurring and in the future, which will appear in all reports. ‘hledger+print --forecast’ is a good way to see them.++ This can be useful for estimating balances into the future, perhaps+experimenting with different scenarios.++ It could also be useful for scripted data entry: you could describe+recurring transactions, and every so often copy the output of ‘print+--forecast’ into the journal.++ The generated transactions will have an extra tag, like+‘generated-transaction:~ PERIODICEXPR’, indicating which periodic rule+generated them. There is also a similar, hidden tag, named+‘_generated-transaction:’, which you can use to reliably match+transactions generated "just now" (rather than ‘print’ed in the past).++ The forecast transactions are generated within a _forecast period_,+which is independent of the report period. (Forecast period sets the+bounds for generated transactions, report period controls which+transactions are reported.) The forecast period begins on:++ • the start date provided within ‘--forecast’’s argument, if any+ • otherwise, the later of+ • the report start date, if specified (with ‘-b’/‘-p’/‘date:’)+ • the day after the latest ordinary transaction in the journal,+ if any++ • otherwise today.++ It ends on:++ • the end date provided within ‘--forecast’’s argument, if any+ • otherwise, the report end date, if specified (with+ ‘-e’/‘-p’/‘date:’)+ • otherwise 180 days (6 months) from today.++ Note, this means that ordinary transactions will suppress periodic+transactions, by default; the periodic transactions will not start until+after the last ordinary transaction. This is usually convenient, but+you can get around it in two ways:++ • If you need to record some transactions in the future, make them+ periodic transactions (with a single occurrence, eg: ‘~+ YYYY-MM-DD’) rather than ordinary transactions. That way they+ won’t suppress other periodic transactions.++ • Or give ‘--forecast’ a period expression argument. A forecast+ period specified this way can overlap ordinary transactions, and+ need not be in the future. Some things to note:++ • You must use ‘=’ between flag and argument; a space won’t+ work.+ • The period expression can specify the forecast period’s start+ date, end date, or both. See also Report start & end date.+ • The period expression should not specify a report interval.+ (Each periodic transaction rule specifies its own interval.)++ Some examples: ‘--forecast=202001-202004’, ‘--forecast=jan-’,+‘--forecast=2021’.+++File: hledger.info, Node: Budgeting, Next: Cost reporting, Prev: Forecasting, Up: Top++21 Budgeting+************++With the balance command’s ‘--budget’ report, each periodic transaction+rule generates recurring budget goals in specified accounts, and goals+and actual performance can be compared. See the balance command’s doc+below.++ See also: Budgeting and Forecasting.+++File: hledger.info, Node: Cost reporting, Next: Valuation, Prev: Budgeting, Up: Top++22 Cost reporting+*****************++This section is about recording the cost of things, in transactions+where one commodity is exchanged for another. Eg an exchange of+currency, or a stock purchase or sale. First, a quick glossary:++ • Conversion - an exchange of one currency or commodity for another.+ Eg a foreign currency exchange, or a purchase or sale of stock or+ cryptocurrency.++ • Conversion transaction - a transaction involving one or more+ conversions.++ • Conversion rate - the cost per unit of one commodity in the other,+ ie the exchange rate.++ • Cost - how much of one commodity was paid to acquire the other.+ And more generally, in hledger docs: the amount exchanged in the+ "secondary" commodity (usually your base currency), whether in a+ purchase or a sale, and whether expressed per unit or in total.+ Also, the "@/@@ PRICE" notation used to represent this.++* Menu:++* -B Convert to cost::+* Equity conversion postings::+* Inferring equity postings from cost::+* Inferring cost from equity postings::+* When to infer cost/equity::+* How to record conversions::+* Cost tips::+++File: hledger.info, Node: -B Convert to cost, Next: Equity conversion postings, Up: Cost reporting++22.1 -B: Convert to cost+========================++As discussed in JOURNAL > Costs, when recording a transaction you can+also record the amount’s cost in another commodity, by adding ‘@+UNITPRICE’ or ‘@@ TOTALPRICE’.++ Then you can see a report with amounts converted to cost, by adding+the ‘-B/--cost’ flag. (Mnemonic: "B" from "cost Basis", as in Ledger).+Eg:++2022-01-01+ assets:dollars $-135 ; 135 dollars is exchanged for..+ assets:euros €100 @ $1.35 ; one hundred euros purchased at $1.35 each++$ hledger bal -N+ $-135 assets:dollars+ €100 assets:euros+$ hledger bal -N -B+ $-135 assets:dollars+ $135 assets:euros # <- the euros' cost++ Notes:++ -B is sensitive to the order of postings when a cost is inferred: the+inferred price will be in the commodity of the last amount. So if+example 3’s postings are reversed, while the transaction is equivalent,+-B shows something different:++2022-01-01+ assets:dollars $-135 ; 135 dollars sold+ assets:euros €100 ; for 100 euros++$ hledger bal -N -B+ €-100 assets:dollars # <- the dollars' selling price+ €100 assets:euros++ The @/@@ cost notation is convenient, but has some drawbacks: it does+not truly balance the transaction, so it disrupts the accounting+equation and tends to causes a non-zero total in balance reports.+++File: hledger.info, Node: Equity conversion postings, Next: Inferring equity postings from cost, Prev: -B Convert to cost, Up: Cost reporting++22.2 Equity conversion postings+===============================++By contrast, conventional double entry bookkeeping (DEB) uses a+different notation: an extra pair of equity postings to balance+conversion transactions. In this style, the above entry might be+written:++2022-01-01 one hundred euros purchased at $1.35 each+ assets:dollars $-135+ equity:conversion $135+ equity:conversion €-100+ assets:euros €100++ This style is more correct, but it’s also more verbose and makes cost+reporting more difficult for PTA tools.++ Happily, current hledger can read either notation, or convert one to+the other when needed, so you can use the one you prefer.++ You can even use cost notation and equivalent conversion postings at+the same time, for clarity. hledger will ignore the redundancy. But be+sure the cost and conversion posting amounts match, or you’ll see a+not-so-clear transaction balancing error message.+++File: hledger.info, Node: Inferring equity postings from cost, Next: Inferring cost from equity postings, Prev: Equity conversion postings, Up: Cost reporting++22.3 Inferring equity postings from cost+========================================++With ‘--infer-equity’, hledger detects transactions written with PTA+cost notation and adds equity conversion postings to them:++2022-01-01+ assets:dollars -$135+ assets:euros €100 @ $1.35++$ hledger print --infer-equity+2022-01-01+ assets:dollars $-135+ assets:euros €100 @ $1.35+ equity:conversion:$-€:€ €-100 ; generated-posting:+ equity:conversion:$-€:$ $135.00 ; generated-posting:++ The conversion account names can be changed with the conversion+account type declaration.++ –infer-equity is useful when when transactions have been recorded+using cost notation, to help preserve the accounting equation and+balance reports’ zero total, or to produce more conventional journal+entries for sharing with non-PTA-users.+++File: hledger.info, Node: Inferring cost from equity postings, Next: When to infer cost/equity, Prev: Inferring equity postings from cost, Up: Cost reporting++22.4 Inferring cost from equity postings+========================================++The reverse operation is possible using ‘--infer-costs’, which detects+transactions written with equity conversion postings and adds cost+notation to them:++2022-01-01+ assets:dollars $-135+ equity:conversion $135+ equity:conversion €-100+ assets:euros €100++$ hledger print --infer-costs+2022-01-01+ assets:dollars $-135 @@ €100+ equity:conversion $135+ equity:conversion €-100+ assets:euros €100++ –infer-costs is useful when combined with -B/–cost, allowing cost+reporting even when transactions have been recorded using equity+postings:++$ hledger print --infer-costs -B+2009-01-01+ assets:dollars €-100+ assets:euros €100++ Notes:++ For ‘--infer-costs’ to work, an exchange must consist of four+postings:++ 1. two non-equity postings+ 2. two equity postings, next to one another+ 3. the equity accounts must be declared, with account type+ ‘V’/‘Conversion’ (or if they are not declared, they must be named+ ‘equity:conversion’, ‘equity:trade’, ‘equity:trading’ or+ subaccounts of these)+ 4. the equity postings’ amounts must exactly match the non-equity+ postings’ amounts.++ Multiple such exchanges can coexist within a single transaction.++ When inferring cost, the order of postings matters: the cost is added+to the first of the non-equity postings involved in the exchange, in the+commodity of the last non-equity posting involved in the exchange. If+you don’t want to write your postings in the required order, you can use+explicit cost notation instead.++ –infer-equity and –infer-costs can be used together, if you have a+mixture of both notations in your journal.+++File: hledger.info, Node: When to infer cost/equity, Next: How to record conversions, Prev: Inferring cost from equity postings, Up: Cost reporting++22.5 When to infer cost/equity+==============================++Inferring equity postings or costs is still fairly new, so not enabled+by default. We’re not sure yet if that should change. Here are two+suggestions to try, experience reports welcome:++ 1. When you use -B, always use –infer-costs as well. Eg: ‘hledger bal+ -B --infer-costs’++ 2. Always run hledger with both flags enabled. Eg: ‘alias hl="hledger+ --infer-equity --infer-costs"’+++File: hledger.info, Node: How to record conversions, Next: Cost tips, Prev: When to infer cost/equity, Up: Cost reporting++22.6 How to record conversions+==============================++Essentially there are four ways to record a conversion transaction in+hledger. Here are all of them, with pros and cons.++* Menu:++* Conversion with implicit cost::+* Conversion with explicit cost::+* Conversion with equity postings::+* Conversion with equity postings and explicit cost::+++File: hledger.info, Node: Conversion with implicit cost, Next: Conversion with explicit cost, Up: How to record conversions++22.6.1 Conversion with implicit cost+------------------------------------++Let’s assume 100 EUR is converted to 120 USD. You can just record the+outflow (100 EUR) and inflow (120 USD) in the appropriate asset account:++2021-01-01+ assets:cash -100 EUR+ assets:cash 120 USD++ hledger will assume this transaction is balanced, inferring that the+conversion rate must be 1 EUR = 1.20 USD. You can see the inferred rate+by using ‘hledger print -x’.++ Pro:++ • Concise, easy++ Con:++ • Less error checking - typos in amounts or commodity symbols may not+ be detected+ • Conversion rate is not clear+ • Disturbs the accounting equation, unless you add the –infer-equity+ flag++ You can prevent accidental implicit conversions due to a mistyped+commodity symbol, by using ‘hledger check commodities’.++ You can prevent implicit conversions entirely, by using ‘hledger+check balancednoautoconversion’, or ‘-s/--strict’.+++File: hledger.info, Node: Conversion with explicit cost, Next: Conversion with equity postings, Prev: Conversion with implicit cost, Up: How to record conversions++22.6.2 Conversion with explicit cost+------------------------------------++You can add the conversion rate using @ notation:++2021-01-01+ assets:cash -100 EUR @ 1.20 USD+ assets:cash 120 USD++ Now hledger will check that 100 * 1.20 = 120, and would report an+error otherwise.++ Pro:++ • Still concise+ • Makes the conversion rate clear+ • Provides more error checking++ Con:++ • Disturbs the accounting equation, unless you add the –infer-equity+ flag+++File: hledger.info, Node: Conversion with equity postings, Next: Conversion with equity postings and explicit cost, Prev: Conversion with explicit cost, Up: How to record conversions++22.6.3 Conversion with equity postings+--------------------------------------++In strict double entry bookkeeping, the above transaction is not+balanced in EUR or in USD, since some EUR disappears, and some USD+appears. This violates the accounting equation (A+L+E=0), and prevents+reports like ‘balancesheetequity’ from showing a zero total.++ The proper way to make it balance is to add a balancing posting for+each commodity, using an equity account:++2021-01-01+ assets:cash -100 EUR+ equity:conversion 100 EUR+ equity:conversion -120 USD+ assets:cash 120 USD++ Pro:++ • Preserves the accounting equation+ • Keeps track of conversions and related gains/losses in one place+ • Standard, works in any double entry accounting system++ Con:++ • More verbose+ • Conversion rate is not obvious+ • Cost reporting requires adding the –infer-costs flag+++File: hledger.info, Node: Conversion with equity postings and explicit cost, Prev: Conversion with equity postings, Up: How to record conversions++22.6.4 Conversion with equity postings and explicit cost+--------------------------------------------------------++Here both equity postings and @ notation are used together.++2021-01-01+ assets:cash -100 EUR @ 1.20 USD+ equity:conversion 100 EUR+ equity:conversion -120 USD+ assets:cash 120 USD++ Pro:++ • Preserves the accounting equation+ • Keeps track of conversions and related gains/losses in one place+ • Makes the conversion rate clear+ • Provides more error checking++ Con:++ • Most verbose+ • Not compatible with ledger+++File: hledger.info, Node: Cost tips, Prev: How to record conversions, Up: Cost reporting++22.7 Cost tips+==============++ • Recording the cost/conversion rate explicitly is good because it+ makes that clear and helps detect errors.+ • Recording equity postings is good because it is correct bookkeeping+ and preserves the accounting equation.+ • Combining these is possible.+ • When you want to see the cost (or sale proceeds) of things, use+ ‘-B’ (short form of ‘--cost’).+ • If you use conversion postings without cost notation, add+ ‘--infer-costs’ also.+ • If you use cost notation without conversion postings, and you want+ to see a balanced balance sheet or print correct journal entries,+ use ‘--infer-equity’.+ • Conversion to cost is performed before valuation (described next).+++File: hledger.info, Node: Valuation, Next: PART 4 COMMANDS, Prev: Cost reporting, Up: Top++23 Valuation+************++Instead of reporting amounts in their original commodity, hledger can+convert them to cost/sale amount (using the conversion rate recorded in+the transaction), and/or to market value (using some market price on a+certain date). This is controlled by the ‘--value=TYPE[,COMMODITY]’+option, which will be described below. We also provide the simpler ‘-V’+and ‘-X COMMODITY’ options, and often one of these is all you need:++* Menu:++* -V Value::+* -X Value in specified commodity::+* Valuation date::+* Finding market price::+* --infer-market-prices market prices from transactions::+* Valuation commodity::+* Simple valuation examples::+* --value Flexible valuation::+* More valuation examples::+* Interaction of valuation and queries::+* Effect of valuation on reports::+++File: hledger.info, Node: -V Value, Next: -X Value in specified commodity, Up: Valuation++23.1 -V: Value+==============++The ‘-V/--market’ flag converts amounts to market value in their default+_valuation commodity_, using the market prices in effect on the+_valuation date(s)_, if any. More on these in a minute.+++File: hledger.info, Node: -X Value in specified commodity, Next: Valuation date, Prev: -V Value, Up: Valuation++23.2 -X: Value in specified commodity+=====================================++The ‘-X/--exchange=COMM’ option is like ‘-V’, except you tell it which+currency you want to convert to, and it tries to convert everything to+that.+++File: hledger.info, Node: Valuation date, Next: Finding market price, Prev: -X Value in specified commodity, Up: Valuation++23.3 Valuation date+===================++Since market prices can change from day to day, market value reports+have a valuation date (or more than one), which determines which market+prices will be used.++ For single period reports, if an explicit report end date is+specified, that will be used as the valuation date; otherwise the+valuation date is the journal’s end date.++ For multiperiod reports, each column/period is valued on the last day+of the period, by default.+++File: hledger.info, Node: Finding market price, Next: --infer-market-prices market prices from transactions, Prev: Valuation date, Up: Valuation++23.4 Finding market price+=========================++To convert a commodity A to its market value in another commodity B,+hledger looks for a suitable market price (exchange rate) as follows, in+this order of preference :++ 1. A _declared market price_ or _inferred market price_: A’s latest+ market price in B on or before the valuation date as declared by a+ P directive, or (with the ‘--infer-market-prices’ flag) inferred+ from costs.++ 2. A _reverse market price_: the inverse of a declared or inferred+ market price from B to A.++ 3. A _forward chain of market prices_: a synthetic price formed by+ combining the shortest chain of "forward" (only 1 above) market+ prices, leading from A to B.++ 4. _Any chain of market prices_: a chain of any market prices,+ including both forward and reverse prices (1 and 2 above), leading+ from A to B.++ There is a limit to the length of these price chains; if hledger+reaches that length without finding a complete chain or exhausting all+possibilities, it will give up (with a "gave up" message visible in+‘--debug=2’ output). That limit is currently 1000.++ Amounts for which no suitable market price can be found, are not+converted.+++File: hledger.info, Node: --infer-market-prices market prices from transactions, Next: Valuation commodity, Prev: Finding market price, Up: Valuation++23.5 –infer-market-prices: market prices from transactions+==========================================================++Normally, market value in hledger is fully controlled by, and requires,+P directives in your journal. Since adding and updating those can be a+chore, and since transactions usually take place at close to market+value, why not use the recorded costs as additional market prices (as+Ledger does) ? Adding the ‘--infer-market-prices’ flag to ‘-V’, ‘-X’ or+‘--value’ enables this.++ So for example, ‘hledger bs -V --infer-market-prices’ will get market+prices both from P directives and from transactions. If both occur on+the same day, the P directive takes precedence.++ There is a downside: value reports can sometimes be affected in+confusing/undesired ways by your journal entries. If this happens to+you, read all of this Valuation section carefully, and try adding+‘--debug’ or ‘--debug=2’ to troubleshoot.++ ‘--infer-market-prices’ can infer market prices from:++ • multicommodity transactions with explicit prices (‘@’/‘@@’)++ • multicommodity transactions with implicit prices (no ‘@’, two+ commodities, unbalanced). (With these, the order of postings+ matters. ‘hledger print -x’ can be useful for troubleshooting.)++ • multicommodity transactions with equity postings, if cost is+ inferred with ‘--infer-costs’.++ There is a limitation (bug) currently: when a valuation commodity is+not specified, prices inferred with ‘--infer-market-prices’ do not help+select a default valuation commodity, as ‘P’ prices would. So+conversion might not happen because no valuation commodity was detected+(‘--debug=2’ will show this). To be safe, specify the valuation+commmodity, eg:++ • ‘-X EUR --infer-market-prices’, not ‘-V --infer-market-prices’+ • ‘--value=then,EUR --infer-market-prices’, not ‘--value=then+ --infer-market-prices’++ Signed costs and market prices can be confusing. For reference, here+is the current behaviour, since hledger 1.25. (If you think it should+work differently, see #1870.)++2022-01-01 Positive Unit prices+ a A 1+ b B -1 @ A 1++2022-01-01 Positive Total prices+ a A 1+ b B -1 @@ A 1+++2022-01-02 Negative unit prices+ a A 1+ b B 1 @ A -1++2022-01-02 Negative total prices+ a A 1+ b B 1 @@ A -1+++2022-01-03 Double Negative unit prices+ a A -1+ b B -1 @ A -1++2022-01-03 Double Negative total prices+ a A -1+ b B -1 @@ A -1++ All of the transactions above are considered balanced (and on each+day, the two transactions are considered equivalent). Here are the+market prices inferred for B:++$ hledger -f- --infer-market-prices prices+P 2022-01-01 B A 1+P 2022-01-01 B A 1.0+P 2022-01-02 B A -1+P 2022-01-02 B A -1.0+P 2022-01-03 B A -1+P 2022-01-03 B A -1.0+++File: hledger.info, Node: Valuation commodity, Next: Simple valuation examples, Prev: --infer-market-prices market prices from transactions, Up: Valuation++23.6 Valuation commodity+========================++*When you specify a valuation commodity (‘-X COMM’ or ‘--value+TYPE,COMM’):*+hledger will convert all amounts to COMM, wherever it can find a+suitable market price (including by reversing or chaining prices).++ *When you leave the valuation commodity unspecified (‘-V’ or ‘--value+TYPE’):*+For each commodity A, hledger picks a default valuation commodity as+follows, in this order of preference:++ 1. The price commodity from the latest P-declared market price for A+ on or before valuation date.++ 2. The price commodity from the latest P-declared market price for A+ on any date. (Allows conversion to proceed when there are inferred+ prices before the valuation date.)++ 3. If there are no P directives at all (any commodity or date) and the+ ‘--infer-market-prices’ flag is used: the price commodity from the+ latest transaction-inferred price for A on or before valuation+ date.++ This means:++ • If you have P directives, they determine which commodities ‘-V’+ will convert, and to what.++ • If you have no P directives, and use the ‘--infer-market-prices’+ flag, costs determine it.++ Amounts for which no valuation commodity can be found are not+converted.+++File: hledger.info, Node: Simple valuation examples, Next: --value Flexible valuation, Prev: Valuation commodity, Up: Valuation++23.7 Simple valuation examples+==============================++Here are some quick examples of ‘-V’:++; one euro is worth this many dollars from nov 1+P 2016/11/01 € $1.10++; purchase some euros on nov 3+2016/11/3+ assets:euros €100+ assets:checking++; the euro is worth fewer dollars by dec 21+P 2016/12/21 € $1.03++ How many euros do I have ?++$ hledger -f t.j bal -N euros+ €100 assets:euros++ What are they worth at end of nov 3 ?++$ hledger -f t.j bal -N euros -V -e 2016/11/4+ $110.00 assets:euros++ What are they worth after 2016/12/21 ? (no report end date+specified, defaults to today)++$ hledger -f t.j bal -N euros -V+ $103.00 assets:euros+++File: hledger.info, Node: --value Flexible valuation, Next: More valuation examples, Prev: Simple valuation examples, Up: Valuation++23.8 –value: Flexible valuation+===============================++‘-V’ and ‘-X’ are special cases of the more general ‘--value’ option:++ --value=TYPE[,COMM] TYPE is then, end, now or YYYY-MM-DD.+ COMM is an optional commodity symbol.+ Shows amounts converted to:+ - default valuation commodity (or COMM) using market prices at posting dates+ - default valuation commodity (or COMM) using market prices at period end(s)+ - default valuation commodity (or COMM) using current market prices+ - default valuation commodity (or COMM) using market prices at some date++ The TYPE part selects cost or value and valuation date:++‘--value=then’++ Convert amounts to their value in the default valuation commodity,+ using market prices on each posting’s date.+‘--value=end’++ Convert amounts to their value in the default valuation commodity,+ using market prices on the last day of the report period (or if+ unspecified, the journal’s end date); or in multiperiod reports,+ market prices on the last day of each subperiod.+‘--value=now’++ Convert amounts to their value in the default valuation commodity+ using current market prices (as of when report is generated).+‘--value=YYYY-MM-DD’++ Convert amounts to their value in the default valuation commodity+ using market prices on this date.++ To select a different valuation commodity, add the optional ‘,COMM’+part: a comma, then the target commodity’s symbol. Eg:+*‘--value=now,EUR’*. hledger will do its best to convert amounts to+this commodity, deducing market prices as described above.+++File: hledger.info, Node: More valuation examples, Next: Interaction of valuation and queries, Prev: --value Flexible valuation, Up: Valuation++23.9 More valuation examples+============================++Here are some examples showing the effect of ‘--value’, as seen with+‘print’:++P 2000-01-01 A 1 B+P 2000-02-01 A 2 B+P 2000-03-01 A 3 B+P 2000-04-01 A 4 B++2000-01-01+ (a) 1 A @ 5 B++2000-02-01+ (a) 1 A @ 6 B++2000-03-01+ (a) 1 A @ 7 B++ Show the cost of each posting:++$ hledger -f- print --cost+2000-01-01+ (a) 5 B++2000-02-01+ (a) 6 B++2000-03-01+ (a) 7 B++ Show the value as of the last day of the report period (2000-02-29):++$ hledger -f- print --value=end date:2000/01-2000/03+2000-01-01+ (a) 2 B++2000-02-01+ (a) 2 B++ With no report period specified, that shows the value as of the last+day of the journal (2000-03-01):++$ hledger -f- print --value=end+2000-01-01+ (a) 3 B++2000-02-01+ (a) 3 B++2000-03-01+ (a) 3 B++ Show the current value (the 2000-04-01 price is still in effect+today):++$ hledger -f- print --value=now+2000-01-01+ (a) 4 B++2000-02-01+ (a) 4 B++2000-03-01+ (a) 4 B++ Show the value on 2000/01/15:++$ hledger -f- print --value=2000-01-15+2000-01-01+ (a) 1 B++2000-02-01+ (a) 1 B++2000-03-01+ (a) 1 B++ You may need to explicitly set a commodity’s display style, when+reverse prices are used. Eg this output might be surprising:++P 2000-01-01 A 2B++2000-01-01+ a 1B+ b++$ hledger print -x -X A+2000-01-01+ a 0+ b 0++ Explanation: because there’s no amount or commodity directive+specifying a display style for A, 0.5A gets the default style, which+shows no decimal digits. Because the displayed amount looks like zero,+the commodity symbol and minus sign are not displayed either. Adding a+commodity directive sets a more useful display style for A:++P 2000-01-01 A 2B+commodity 0.00A++2000-01-01+ a 1B+ b++$ hledger print -X A+2000-01-01+ a 0.50A+ b -0.50A+++File: hledger.info, Node: Interaction of valuation and queries, Next: Effect of valuation on reports, Prev: More valuation examples, Up: Valuation++23.10 Interaction of valuation and queries+==========================================++When matching postings based on queries in the presence of valuation,+the following happens.++ 1. The query is separated into two parts:+ 1. the currency (‘cur:’) or amount (‘amt:’).+ 2. all other parts.++ 2. The postings are matched to the currency and amount queries based+ on pre-valued amounts.+ 3. Valuation is applied to the postings.+ 4. The postings are matched to the other parts of the query based on+ post-valued amounts.++ See: 1625+++File: hledger.info, Node: Effect of valuation on reports, Prev: Interaction of valuation and queries, Up: Valuation++23.11 Effect of valuation on reports+====================================++Here is a reference for how valuation is supposed to affect each part of+hledger’s reports (and a glossary). (It’s wide, you’ll have to scroll+sideways.) It may be useful when troubleshooting. If you find+problems, please report them, ideally with a reproducible example.+Related: #329, #1083.++Report ‘-B’, ‘-V’, ‘-X’ ‘--value=then’ ‘--value=end’‘--value=DATE’,+type ‘--cost’ ‘--value=now’+------------------------------------------------------------------------------+*print*+posting cost value at value at posting value at value+amounts report end date report or at+ or today journal DATE/today+ end+balance unchanged unchanged unchanged unchanged unchanged+assertions/assignments+*register*+starting cost value at valued at day value at value+balance report or each historical report or at+(-H) journal posting was made journal DATE/today+ end end+starting cost value at valued at day value at value+balance day before each historical day before at+(-H) report or posting was made report or DATE/today+with journal journal+report start start+interval+posting cost value at value at posting value at value+amounts report or date report or at+ journal journal DATE/today+ end end+summary summarised value at sum of postings value at value+posting cost period in interval, period at+amounts ends valued at ends DATE/today+with interval start+report+interval+running sum/average sum/average sum/average of sum/average sum/average+total/averageof of displayed values of of+ displayed displayed displayed displayed+ values values values values+*balance+(bs,+bse, cf,+is)*+balance sums of value at value at posting value at value+changes costs report end date report or at+ or today journal DATE/today+ of sums of end of of+ postings sums of sums+ postings of+ postings+budget like like like balance like like+amounts balance balance changes balances balance+(–budget) changes changes changes+grand sum of sum of sum of displayed sum of sum of+total displayed displayed valued displayed displayed+ values values values values+*balance+(bs,+bse, cf,+is) with+report+interval*+starting sums of value at sums of values value at sums+balances costs of report of postings report of+(-H) postings start of before report start of postings+ before sums of start at sums of before+ report all respective all report+ start postings posting dates postings start+ before before+ report report+ start start+balance sums of same as sums of values balance value+changes costs of –value=end of postings in change in at+(bal, postings period at each DATE/today+is, bs in period respective period, of+–change, posting dates valued at sums+cf period of+–change) ends postings+end sums of same as sums of values period end value+balances costs of –value=end of postings from balances, at+(bal -H, postings before period valued at DATE/today+is –H, from start to period period of+bs, cf) before end at ends sums+ report respective of+ start to posting dates postings+ period end+budget like like like balance like like+amounts balance balance changes/end balances balance+(–budget) changes/end changes/end balances changes/end+ balances balances balances+row sums, sums, sums, averages sums, sums,+totals, averages averages of displayed averages averages+row of of values of of+averages displayed displayed displayed displayed+(-T, -A) values values values values+column sums of sums of sums of sums of sums+totals displayed displayed displayed values displayed of+ values values values displayed+ values+grand sum, sum, sum, average of sum, sum,+total, average of average of column totals average of average+grand column column column of+average totals totals totals column+ totals++ ‘--cumulative’ is omitted to save space, it works like ‘-H’ but with+a zero starting balance.++ *Glossary:*++_cost_++ calculated using price(s) recorded in the transaction(s).+_value_++ market value using available market price declarations, or the+ unchanged amount if no conversion rate can be found.+_report start_++ the first day of the report period specified with -b or -p or+ date:, otherwise today.+_report or journal start_++ the first day of the report period specified with -b or -p or+ date:, otherwise the earliest transaction date in the journal,+ otherwise today.+_report end_++ the last day of the report period specified with -e or -p or date:,+ otherwise today.+_report or journal end_++ the last day of the report period specified with -e or -p or date:,+ otherwise the latest transaction date in the journal, otherwise+ today.+_report interval_++ a flag (-D/-W/-M/-Q/-Y) or period expression that activates the+ report’s multi-period mode (whether showing one or many+ subperiods).+++File: hledger.info, Node: PART 4 COMMANDS, Next: PART 5 COMMON TASKS, Prev: Valuation, Up: Top++24 PART 4: COMMANDS+*******************++* Menu:++* Commands overview::+* accounts::+* activity::+* add::+* aregister::+* balance::+* balancesheet::+* balancesheetequity::+* cashflow::+* check::+* close::+* codes::+* commodities::+* descriptions::+* diff::+* files::+* help::+* import::+* incomestatement::+* notes::+* payees::+* prices::+* print::+* register::+* rewrite::+* roi::+* stats::+* tags::+* test::+++File: hledger.info, Node: Commands overview, Next: accounts, Up: PART 4 COMMANDS++24.1 Commands overview+======================++Here are the built-in commands:++* Menu:++* DATA ENTRY::+* DATA CREATION::+* DATA MANAGEMENT::+* REPORTS FINANCIAL::+* REPORTS VERSATILE::+* REPORTS BASIC::+* HELP::+* ADD-ONS::+++File: hledger.info, Node: DATA ENTRY, Next: DATA CREATION, Up: Commands overview++24.1.1 DATA ENTRY+-----------------++These data entry commands are the only ones which can modify your+journal file.++ • add - add transactions using terminal prompts+ • import - add new transactions from other files, eg CSV files+++File: hledger.info, Node: DATA CREATION, Next: DATA MANAGEMENT, Prev: DATA ENTRY, Up: Commands overview++24.1.2 DATA CREATION+--------------------++ • close - generate balance-zeroing/restoring transactions+ • rewrite - generate auto postings, like print –auto+++File: hledger.info, Node: DATA MANAGEMENT, Next: REPORTS FINANCIAL, Prev: DATA CREATION, Up: Commands overview++24.1.3 DATA MANAGEMENT+----------------------++ • check - check for various kinds of error in the data+ • diff - compare account transactions in two journal files+++File: hledger.info, Node: REPORTS FINANCIAL, Next: REPORTS VERSATILE, Prev: DATA MANAGEMENT, Up: Commands overview++24.1.4 REPORTS, FINANCIAL+-------------------------++ • aregister (areg) - show transactions in a particular account+ • balancesheet (bs) - show assets, liabilities and net worth+ • balancesheetequity (bse) - show assets, liabilities and equity+ • cashflow (cf) - show changes in liquid assets+ • incomestatement (is) - show revenues and expenses+++File: hledger.info, Node: REPORTS VERSATILE, Next: REPORTS BASIC, Prev: REPORTS FINANCIAL, Up: Commands overview++24.1.5 REPORTS, VERSATILE+-------------------------++ • balance (bal) - show balance changes, end balances, budgets,+ gains..+ • print - show transactions or export journal data+ • register (reg) - show postings in one or more accounts & running+ total+ • roi - show return on investments+++File: hledger.info, Node: REPORTS BASIC, Next: HELP, Prev: REPORTS VERSATILE, Up: Commands overview++24.1.6 REPORTS, BASIC+---------------------++ • accounts - show account names+ • activity - show bar charts of posting counts per period+ • codes - show transaction codes+ • commodities - show commodity/currency symbols+ • descriptions - show transaction descriptions+ • files - show input file paths+ • notes - show note parts of transaction descriptions+ • payees - show payee parts of transaction descriptions+ • prices - show market prices+ • stats - show journal statistics+ • tags - show tag names+ • test - run self tests+++File: hledger.info, Node: HELP, Next: ADD-ONS, Prev: REPORTS BASIC, Up: Commands overview++24.1.7 HELP+-----------++ • help - show the hledger manual with info/man/pager+++File: hledger.info, Node: ADD-ONS, Prev: HELP, Up: Commands overview++24.1.8 ADD-ONS+--------------++And here are some typical add-on commands. Some of these are installed+by the hledger-install script. If installed, they will appear in+hledger’s commands list:++ • ui - run hledger’s terminal UI+ • web - run hledger’s web UI+ • iadd - add transactions using a TUI (currently hard to build)+ • interest - generate interest transactions+ • stockquotes - download market prices from AlphaVantage+ • Scripts and add-ons - check-fancyassertions, edit, fifo, git, move,+ pijul, plot, and more..++ Next, each command is described in detail, in alphabetical order.+++File: hledger.info, Node: accounts, Next: activity, Prev: Commands overview, Up: PART 4 COMMANDS++24.2 accounts+=============++Show account names.++ This command lists account names. By default it shows all known+accounts, either used in transactions or declared with account+directives.++ With query arguments, only matched account names and account names+referenced by matched postings are shown.++ Or it can show just the used accounts (‘--used’/‘-u’), the declared+accounts (‘--declared’/‘-d’), the accounts declared but not used+(‘--unused’), the accounts used but not declared (‘--undeclared’), or+the first account matched by an account name pattern, if any (‘--find’).++ It shows a flat list by default. With ‘--tree’, it uses indentation+to show the account hierarchy. In flat mode you can add ‘--drop N’ to+omit the first few account name components. Account names can be+depth-clipped with ‘depth:N’ or ‘--depth N’ or ‘-N’.++ With ‘--types’, it also shows each account’s type, if it’s known.+(See Declaring accounts > Account types.)++ With ‘--positions’, it also shows the file and line number of each+account’s declaration, if any, and the account’s overall declaration+order; these may be useful when troubleshooting account display order.++ With ‘--directives’, it adds the ‘account’ keyword, showing valid+account directives which can be pasted into a journal file. This is+useful together with ‘--undeclared’ when updating your account+declarations to satisfy ‘hledger check accounts’.++ The ‘--find’ flag can be used to look up a single account name, in+the same way that the ‘aregister’ command does. It returns the+alphanumerically-first matched account name, or if none can be found, it+fails with a non-zero exit code.++ Examples:++$ hledger accounts+assets:bank:checking+assets:bank:saving+assets:cash+expenses:food+expenses:supplies+income:gifts+income:salary+liabilities:debts++$ hledger accounts --undeclared --directives >> $LEDGER_FILE+$ hledger check accounts+++File: hledger.info, Node: activity, Next: add, Prev: accounts, Up: PART 4 COMMANDS++24.3 activity+=============++Show an ascii barchart of posting counts per interval.++ The activity command displays an ascii histogram showing transaction+counts by day, week, month or other reporting interval (by day is the+default). With query arguments, it counts only matched transactions.++ Examples:++$ hledger activity --quarterly+2008-01-01 **+2008-04-01 *******+2008-07-01 +2008-10-01 **+++File: hledger.info, Node: add, Next: aregister, Prev: activity, Up: PART 4 COMMANDS++24.4 add+========++Prompt for transactions and add them to the journal. Any arguments will+be used as default inputs for the first N prompts.++ Many hledger users edit their journals directly with a text editor,+or generate them from CSV. For more interactive data entry, there is the+‘add’ command, which prompts interactively on the console for new+transactions, and appends them to the main journal file (which should be+in journal format). Existing transactions are not changed. This is one+of the few hledger commands that writes to the journal file (see also+‘import’).++ To use it, just run ‘hledger add’ and follow the prompts. You can+add as many transactions as you like; when you are finished, enter ‘.’+or press control-d or control-c to exit.++ Features:++ • add tries to provide useful defaults, using the most similar (by+ description) recent transaction (filtered by the query, if any) as+ a template.+ • You can also set the initial defaults with command line arguments.+ • Readline-style edit keys can be used during data entry.+ • The tab key will auto-complete whenever possible - accounts,+ payees/descriptions, dates (‘yesterday’, ‘today’, ‘tomorrow’). If+ the input area is empty, it will insert the default value.+ • If the journal defines a default commodity, it will be added to any+ bare numbers entered.+ • A parenthesised transaction code may be entered following a date.+ • Comments and tags may be entered following a description or amount.+ • If you make a mistake, enter ‘<’ at any prompt to go one step+ backward.+ • Input prompts are displayed in a different colour when the terminal+ supports it.++ Example (see https://hledger.org/add.html for a detailed tutorial):++$ hledger add+Adding transactions to journal file /src/hledger/examples/sample.journal+Any command line arguments will be used as defaults.+Use tab key to complete, readline keys to edit, enter to accept defaults.+An optional (CODE) may follow transaction dates.+An optional ; COMMENT may follow descriptions or amounts.+If you make a mistake, enter < at any prompt to go one step backward.+To end a transaction, enter . when prompted.+To quit, enter . at a date prompt or press control-d or control-c.+Date [2015/05/22]: +Description: supermarket+Account 1: expenses:food+Amount 1: $10+Account 2: assets:checking+Amount 2 [$-10.0]: +Account 3 (or . or enter to finish this transaction): .+2015/05/22 supermarket+ expenses:food $10+ assets:checking $-10.0++Save this transaction to the journal ? [y]: +Saved.+Starting the next transaction (. or ctrl-D/ctrl-C to quit)+Date [2015/05/22]: <CTRL-D> $++ On Microsoft Windows, the add command makes sure that no part of the+file path ends with a period, as that would cause problems (#1056).+++File: hledger.info, Node: aregister, Next: balance, Prev: add, Up: PART 4 COMMANDS++24.5 aregister+==============++(areg)++ Show the transactions and running historical balance of a single+account, with each transaction displayed as one line.++ ‘aregister’ shows the overall transactions affecting a particular+account (and any subaccounts). Each report line represents one+transaction in this account. Transactions before the report start date+are always included in the running balance (‘--historical’ mode is+always on).++ This is a more "real world", bank-like view than the ‘register’+command (which shows individual postings, possibly from multiple+accounts, not necessarily in historical mode). As a quick rule of+thumb: - use ‘aregister’ for reviewing and reconciling real-world+asset/liability accounts - use ‘register’ for reviewing detailed+revenues/expenses.++ ‘aregister’ requires one argument: the account to report on. You can+write either the full account name, or a case-insensitive regular+expression which will select the alphabetically first matched account.++ When there are multiple matches, the alphabetically-first choice can+be surprising; eg if you have ‘assets:per:checking 1’ and+‘assets:biz:checking 2’ accounts, ‘hledger areg checking’ would select+‘assets:biz:checking 2’. It’s just a convenience to save typing, so if+in doubt, write the full account name, or a distinctive substring that+matches uniquely.++ Transactions involving subaccounts of this account will also be+shown. ‘aregister’ ignores depth limits, so its final total will always+match a balance report with similar arguments.++ Any additional arguments form a query which will filter the+transactions shown. Note some queries will disturb the running balance,+causing it to be different from the account’s real-world running+balance.++ An example: this shows the transactions and historical running+balance during july, in the first account whose name contains+"checking":++$ hledger areg checking date:jul++ Each ‘aregister’ line item shows:++ • the transaction’s date (or the relevant posting’s date if+ different, see below)+ • the names of all the other account(s) involved in this transaction+ (probably abbreviated)+ • the total change to this account’s balance from this transaction+ • the account’s historical running balance after this transaction.++ Transactions making a net change of zero are not shown by default;+add the ‘-E/--empty’ flag to show them.++ For performance reasons, column widths are chosen based on the first+1000 lines; this means unusually wide values in later lines can cause+visual discontinuities as column widths are adjusted. If you want to+ensure perfect alignment, at the cost of more time and memory, use the+‘--align-all’ flag.++ This command also supports the output destination and output format+options. The output formats supported are ‘txt’, ‘csv’, and ‘json’.++* Menu:++* aregister and custom posting dates::+++File: hledger.info, Node: aregister and custom posting dates, Up: aregister++24.5.1 aregister and custom posting dates+-----------------------------------------++Transactions whose date is outside the report period can still be shown,+if they have a posting to this account dated inside the report period.+(And in this case it’s the posting date that is shown.) This ensures+that ‘aregister’ can show an accurate historical running balance,+matching the one shown by ‘register -H’ with the same arguments.++ To filter strictly by transaction date instead, add the ‘--txn-dates’+flag. If you use this flag and some of your postings have custom dates,+it’s probably best to assume the running balance is wrong.+++File: hledger.info, Node: balance, Next: balancesheet, Prev: aregister, Up: PART 4 COMMANDS++24.6 balance+============++(bal)++ Show accounts and their balances.++ ‘balance’ is one of hledger’s oldest and most versatile commands, for+listing account balances, balance changes, values, value changes and+more, during one time period or many. Generally it shows a table, with+rows representing accounts, and columns representing periods.++ Note there are some higher-level variants of the ‘balance’ command+with convenient defaults, which can be simpler to use: ‘balancesheet’,+‘balancesheetequity’, ‘cashflow’ and ‘incomestatement’. When you need+more control, then use ‘balance’.++* Menu:++* balance features::+* Simple balance report::+* Balance report line format::+* Filtered balance report::+* List or tree mode::+* Depth limiting::+* Dropping top-level accounts::+* Showing declared accounts::+* Sorting by amount::+* Percentages::+* Multi-period balance report::+* Balance change end balance::+* Balance report types::+* Budget report::+* Data layout::+* Useful balance reports::+++File: hledger.info, Node: balance features, Next: Simple balance report, Up: balance++24.6.1 balance features+-----------------------++Here’s a quick overview of the ‘balance’ command’s features, followed by+more detailed descriptions and examples. Many of these work with the+higher-level commands as well.++ ‘balance’ can show..++ • accounts as a list (‘-l’) or a tree (‘-t’)+ • optionally depth-limited (‘-[1-9]’)+ • sorted by declaration order and name, or by amount++ ..and their..++ • balance changes (the default)+ • or actual and planned balance changes (‘--budget’)+ • or value of balance changes (‘-V’)+ • or change of balance values (‘--valuechange’)+ • or unrealised capital gain/loss (‘--gain’)++ ..in..++ • one time period (the whole journal period by default)+ • or multiple periods (‘-D’, ‘-W’, ‘-M’, ‘-Q’, ‘-Y’, ‘-p INTERVAL’)++ ..either..++ • per period (the default)+ • or accumulated since report start date (‘--cumulative’)+ • or accumulated since account creation (‘--historical/-H’)++ ..possibly converted to..++ • cost (‘--value=cost[,COMM]’/‘--cost’/‘-B’)+ • or market value, as of transaction dates (‘--value=then[,COMM]’)+ • or at period ends (‘--value=end[,COMM]’)+ • or now (‘--value=now’)+ • or at some other date (‘--value=YYYY-MM-DD’)++ ..with..++ • totals (‘-T’), averages (‘-A’), percentages (‘-%’), inverted sign+ (‘--invert’)+ • rows and columns swapped (‘--transpose’)+ • another field used as account name (‘--pivot’)+ • custom-formatted line items (single-period reports only)+ (‘--format’)+ • commodities displayed on the same line or multiple lines+ (‘--layout’)++ This command supports the output destination and output format+options, with output formats ‘txt’, ‘csv’, ‘json’, and (multi-period+reports only:) ‘html’. In ‘txt’ output in a colour-supporting terminal,+negative amounts are shown in red.++ The ‘--related’/‘-r’ flag shows the balance of the _other_ postings+in the transactions of the postings which would normally be shown.+++File: hledger.info, Node: Simple balance report, Next: Balance report line format, Prev: balance features, Up: balance++24.6.2 Simple balance report+----------------------------++With no arguments, ‘balance’ shows a list of all accounts and their+change of balance - ie, the sum of posting amounts, both inflows and+outflows - during the entire period of the journal. ("Simple" here+means just one column of numbers, covering a single period. You can+also have multi-period reports, described later.)++ For real-world accounts, these numbers will normally be their end+balance at the end of the journal period; more on this below.++ Accounts are sorted by declaration order if any, and then+alphabetically by account name. For instance (using+examples/sample.journal):++$ hledger -f examples/sample.journal bal+ $1 assets:bank:saving+ $-2 assets:cash+ $1 expenses:food+ $1 expenses:supplies+ $-1 income:gifts+ $-1 income:salary+ $1 liabilities:debts+--------------------+ 0 ++ Accounts with a zero balance (and no non-zero subaccounts, in tree+mode - see below) are hidden by default. Use ‘-E/--empty’ to show them+(revealing ‘assets:bank:checking’ here):++$ hledger -f examples/sample.journal bal -E+ 0 assets:bank:checking+ $1 assets:bank:saving+ $-2 assets:cash+ $1 expenses:food+ $1 expenses:supplies+ $-1 income:gifts+ $-1 income:salary+ $1 liabilities:debts+--------------------+ 0 ++ The total of the amounts displayed is shown as the last line, unless+‘-N’/‘--no-total’ is used.+++File: hledger.info, Node: Balance report line format, Next: Filtered balance report, Prev: Simple balance report, Up: balance++24.6.3 Balance report line format+---------------------------------++For single-period balance reports displayed in the terminal (only), you+can use ‘--format FMT’ to customise the format and content of each line.+Eg:++$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"+ assets $-1+ bank:saving $1+ cash $-2+ expenses $2+ food $1+ supplies $1+ income $-2+ gifts $-1+ salary $-1+ liabilities:debts $1+---------------------------------+ 0++ The FMT format string specifies the formatting applied to each+account/balance pair. It may contain any suitable text, with data+fields interpolated like so:++ ‘%[MIN][.MAX](FIELDNAME)’++ • MIN pads with spaces to at least this width (optional)++ • MAX truncates at this width (optional)++ • FIELDNAME must be enclosed in parentheses, and can be one of:++ • ‘depth_spacer’ - a number of spaces equal to the account’s+ depth, or if MIN is specified, MIN * depth spaces.+ • ‘account’ - the account’s name+ • ‘total’ - the account’s balance/posted total, right justified++ Also, FMT can begin with an optional prefix to control how+multi-commodity amounts are rendered:++ • ‘%_’ - render on multiple lines, bottom-aligned (the default)+ • ‘%^’ - render on multiple lines, top-aligned+ • ‘%,’ - render on one line, comma-separated++ There are some quirks. Eg in one-line mode, ‘%(depth_spacer)’ has no+effect, instead ‘%(account)’ has indentation built in. Experimentation+may be needed to get pleasing results.++ Some example formats:++ • ‘%(total)’ - the account’s total+ • ‘%-20.20(account)’ - the account’s name, left justified, padded to+ 20 characters and clipped at 20 characters+ • ‘%,%-50(account) %25(total)’ - account name padded to 50+ characters, total padded to 20 characters, with multiple+ commodities rendered on one line+ • ‘%20(total) %2(depth_spacer)%-(account)’ - the default format for+ the single-column balance report+++File: hledger.info, Node: Filtered balance report, Next: List or tree mode, Prev: Balance report line format, Up: balance++24.6.4 Filtered balance report+------------------------------++You can show fewer accounts, a different time period, totals from+cleared transactions only, etc. by using query arguments or options to+limit the postings being matched. Eg:++$ hledger -f examples/sample.journal bal --cleared assets date:200806+ $-2 assets:cash+--------------------+ $-2 +++File: hledger.info, Node: List or tree mode, Next: Depth limiting, Prev: Filtered balance report, Up: balance++24.6.5 List or tree mode+------------------------++By default, or with ‘-l/--flat’, accounts are shown as a flat list with+their full names visible, as in the examples above.++ With ‘-t/--tree’, the account hierarchy is shown, with subaccounts’+"leaf" names indented below their parent:++$ hledger -f examples/sample.journal balance+ $-1 assets+ $1 bank:saving+ $-2 cash+ $2 expenses+ $1 food+ $1 supplies+ $-2 income+ $-1 gifts+ $-1 salary+ $1 liabilities:debts+--------------------+ 0++ Notes:++ • "Boring" accounts are combined with their subaccount for more+ compact output, unless ‘--no-elide’ is used. Boring accounts have+ no balance of their own and just one subaccount (eg ‘assets:bank’+ and ‘liabilities’ above).++ • All balances shown are "inclusive", ie including the balances from+ all subaccounts. Note this means some repetition in the output,+ which requires explanation when sharing reports with+ non-plaintextaccounting-users. A tree mode report’s final total is+ the sum of the top-level balances shown, not of all the balances+ shown.++ • Each group of sibling accounts (ie, under a common parent) is+ sorted separately.+++File: hledger.info, Node: Depth limiting, Next: Dropping top-level accounts, Prev: List or tree mode, Up: balance++24.6.6 Depth limiting+---------------------++With a ‘depth:NUM’ query, or ‘--depth NUM’ option, or just ‘-NUM’ (eg:+‘-3’) balance reports will show accounts only to the specified depth,+hiding the deeper subaccounts. This can be useful for getting an+overview without too much detail.++ Account balances at the depth limit always include the balances from+any deeper subaccounts (even in list mode). Eg, limiting to depth 1:++$ hledger -f examples/sample.journal balance -1+ $-1 assets+ $2 expenses+ $-2 income+ $1 liabilities+--------------------+ 0 +++File: hledger.info, Node: Dropping top-level accounts, Next: Showing declared accounts, Prev: Depth limiting, Up: balance++24.6.7 Dropping top-level accounts+----------------------------------++You can also hide one or more top-level account name parts, using+‘--drop NUM’. This can be useful for hiding repetitive top-level+account names:++$ hledger -f examples/sample.journal bal expenses --drop 1+ $1 food+ $1 supplies+--------------------+ $2 +++File: hledger.info, Node: Showing declared accounts, Next: Sorting by amount, Prev: Dropping top-level accounts, Up: balance++24.6.8 Showing declared accounts+--------------------------------++With ‘--declared’, accounts which have been declared with an account+directive will be included in the balance report, even if they have no+transactions. (Since they will have a zero balance, you will also need+‘-E/--empty’ to see them.)++ More precisely, _leaf_ declared accounts (with no subaccounts) will+be included, since those are usually the more useful in reports.++ The idea of this is to be able to see a useful "complete" balance+report, even when you don’t have transactions in all of your declared+accounts yet.+++File: hledger.info, Node: Sorting by amount, Next: Percentages, Prev: Showing declared accounts, Up: balance++24.6.9 Sorting by amount+------------------------++With ‘-S/--sort-amount’, accounts with the largest (most positive)+balances are shown first. Eg: ‘hledger bal expenses -MAS’ shows your+biggest averaged monthly expenses first. When more than one commodity+is present, they will be sorted by the alphabetically earliest commodity+first, and then by subsequent commodities (if an amount is missing a+commodity, it is treated as 0).++ Revenues and liability balances are typically negative, however, so+‘-S’ shows these in reverse order. To work around this, you can add+‘--invert’ to flip the signs. (Or, use one of the higher-level reports,+which flip the sign automatically. Eg: ‘hledger incomestatement -MAS’).+++File: hledger.info, Node: Percentages, Next: Multi-period balance report, Prev: Sorting by amount, Up: balance++24.6.10 Percentages+-------------------++With ‘-%/--percent’, balance reports show each account’s value expressed+as a percentage of the (column) total.++ Note it is not useful to calculate percentages if the amounts in a+column have mixed signs. In this case, make a separate report for each+sign, eg:++$ hledger bal -% amt:`>0`+$ hledger bal -% amt:`<0`++ Similarly, if the amounts in a column have mixed commodities, convert+them to one commodity with ‘-B’, ‘-V’, ‘-X’ or ‘--value’, or make a+separate report for each commodity:++$ hledger bal -% cur:\\$+$ hledger bal -% cur:€+++File: hledger.info, Node: Multi-period balance report, Next: Balance change end balance, Prev: Percentages, Up: balance++24.6.11 Multi-period balance report+-----------------------------------++With a report interval (set by the ‘-D/--daily’, ‘-W/--weekly’,+‘-M/--monthly’, ‘-Q/--quarterly’, ‘-Y/--yearly’, or ‘-p/--period’ flag),+‘balance’ shows a tabular report, with columns representing successive+time periods (and a title):++$ hledger -f examples/sample.journal bal --quarterly income expenses -E+Balance changes in 2008:++ || 2008q1 2008q2 2008q3 2008q4 +===================++=================================+ expenses:food || 0 $1 0 0 + expenses:supplies || 0 $1 0 0 + income:gifts || 0 $-1 0 0 + income:salary || $-1 0 0 0 +-------------------++---------------------------------+ || $-1 $1 0 0 ++ Notes:++ • The report’s start/end dates will be expanded, if necessary, to+ fully encompass the displayed subperiods (so that the first and+ last subperiods have the same duration as the others).+ • Leading and trailing periods (columns) containing all zeroes are+ not shown, unless ‘-E/--empty’ is used.+ • Accounts (rows) containing all zeroes are not shown, unless+ ‘-E/--empty’ is used.+ • Amounts with many commodities are shown in abbreviated form, unless+ ‘--no-elide’ is used. _(experimental)_+ • Average and/or total columns can be added with the ‘-A/--average’+ and ‘-T/--row-total’ flags.+ • The ‘--transpose’ flag can be used to exchange rows and columns.+ • The ‘--pivot FIELD’ option causes a different transaction field to+ be used as "account name". See PIVOTING.++ Multi-period reports with many periods can be too wide for easy+viewing in the terminal. Here are some ways to handle that:++ • Hide the totals row with ‘-N/--no-total’+ • Convert to a single currency with ‘-V’+ • Maximize the terminal window+ • Reduce the terminal’s font size+ • View with a pager like less, eg: ‘hledger bal -D --color=yes | less+ -RS’+ • Output as CSV and use a CSV viewer like visidata (‘hledger bal -D+ -O csv | vd -f csv’), Emacs’ csv-mode (‘M-x csv-mode, C-c C-a’), or+ a spreadsheet (‘hledger bal -D -o a.csv && open a.csv’)+ • Output as HTML and view with a browser: ‘hledger bal -D -o a.html+ && open a.html’+++File: hledger.info, Node: Balance change end balance, Next: Balance report types, Prev: Multi-period balance report, Up: balance++24.6.12 Balance change, end balance+-----------------------------------++It’s important to be clear on the meaning of the numbers shown in+balance reports. Here is some terminology we use:++ A *_balance change_* is the net amount added to, or removed from, an+account during some period.++ An *_end balance_* is the amount accumulated in an account as of some+date (and some time, but hledger doesn’t store that; assume end of day+in your timezone). It is the sum of previous balance changes.++ We call it a *_historical end balance_* if it includes all balance+changes since the account was created. For a real world account, this+means it will match the "historical record", eg the balances reported in+your bank statements or bank web UI. (If they are correct!)++ In general, balance changes are what you want to see when reviewing+revenues and expenses, and historical end balances are what you want to+see when reviewing or reconciling asset, liability and equity accounts.++ ‘balance’ shows balance changes by default. To see accurate+historical end balances:++ 1. Initialise account starting balances with an "opening balances"+ transaction (a transfer from equity to the account), unless the+ journal covers the account’s full lifetime.++ 2. Include all of of the account’s prior postings in the report, by+ not specifying a report start date, or by using the+ ‘-H/--historical’ flag. (‘-H’ causes report start date to be+ ignored when summing postings.)+++File: hledger.info, Node: Balance report types, Next: Budget report, Prev: Balance change end balance, Up: balance++24.6.13 Balance report types+----------------------------++The balance command is quite flexible; here is the full detail on how to+control what it reports. If the following seems complicated, don’t+worry - this is for advanced reporting, and it does typically take some+time and experimentation to get clear on all these report modes.++ There are three important option groups:++ ‘hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]+...’++* Menu:++* Calculation type::+* Accumulation type::+* Valuation type::+* Combining balance report types::+++File: hledger.info, Node: Calculation type, Next: Accumulation type, Up: Balance report types++24.6.13.1 Calculation type+..........................++The basic calculation to perform for each table cell. It is one of:++ • ‘--sum’ : sum the posting amounts (*default*)+ • ‘--budget’ : sum the amounts, but also show the budget goal amount+ (for each account/period)+ • ‘--valuechange’ : show the change in period-end historical balance+ values (caused by deposits, withdrawals, and/or market price+ fluctuations)+ • ‘--gain’ : show the unrealised capital gain/loss, (the current+ valued balance minus each amount’s original cost)+++File: hledger.info, Node: Accumulation type, Next: Valuation type, Prev: Calculation type, Up: Balance report types++24.6.13.2 Accumulation type+...........................++How amounts should accumulate across report periods. Another way to say+it: which time period’s postings should contribute to each cell’s+calculation. It is one of:++ • ‘--change’ : calculate with postings from column start to column+ end, ie "just this column". Typically used to see+ revenues/expenses. (*default for balance, incomestatement*)++ • ‘--cumulative’ : calculate with postings from report start to+ column end, ie "previous columns plus this column". Typically used+ to show changes accumulated since the report’s start date. Not+ often used.++ • ‘--historical/-H’ : calculate with postings from journal start to+ column end, ie "all postings from before report start date until+ this column’s end". Typically used to see historical end balances+ of assets/liabilities/equity. (*default for balancesheet,+ balancesheetequity, cashflow*)+++File: hledger.info, Node: Valuation type, Next: Combining balance report types, Prev: Accumulation type, Up: Balance report types++24.6.13.3 Valuation type+........................++Which kind of value or cost conversion should be applied, if any, before+displaying the report. It is one of:++ • no valuation type : don’t convert to cost or value (*default*)+ • ‘--value=cost[,COMM]’ : convert amounts to cost (then optionally to+ some other commodity)+ • ‘--value=then[,COMM]’ : convert amounts to market value on+ transaction dates+ • ‘--value=end[,COMM]’ : convert amounts to market value on period+ end date(s)+ (*default with ‘--valuechange’, ‘--gain’*)+ • ‘--value=now[,COMM]’ : convert amounts to market value on today’s+ date+ • ‘--value=YYYY-MM-DD[,COMM]’ : convert amounts to market value on+ another date++ or one of the equivalent simpler flags:++ • ‘-B/--cost’ : like –value=cost (though, note –cost and –value are+ independent options which can both be used at once)+ • ‘-V/--market’ : like –value=end+ • ‘-X COMM/--exchange COMM’ : like –value=end,COMM++ See Cost reporting and Valuation for more about these.+++File: hledger.info, Node: Combining balance report types, Prev: Valuation type, Up: Balance report types++24.6.13.4 Combining balance report types+........................................++Most combinations of these options should produce reasonable reports,+but if you find any that seem wrong or misleading, let us know. The+following restrictions are applied:++ • ‘--valuechange’ implies ‘--value=end’+ • ‘--valuechange’ makes ‘--change’ the default when used with the+ ‘balancesheet’/‘balancesheetequity’ commands+ • ‘--cumulative’ or ‘--historical’ disables ‘--row-total/-T’++ For reference, here is what the combinations of accumulation and+valuation show:++Valuation:>no valuation ‘--value= then’ ‘--value= end’ ‘--value=+Accumulation:v YYYY-MM-DD+ /now’+-----------------------------------------------------------------------------+‘--change’change in sum of period-end DATE-value+ period posting-date value of of change in+ market values change in period+ in period period+‘--cumulative’change from sum of period-end DATE-value+ report start to posting-date value of of change+ period end market values change from from report+ from report report start start to+ start to period to period end period end+ end+‘--historicalchange from sum of period-end DATE-value+/-H’ journal start posting-date value of of change+ to period end market values change from from journal+ (historical end from journal journal start start to+ balance) start to period to period end period end+ end+++File: hledger.info, Node: Budget report, Next: Data layout, Prev: Balance report types, Up: balance++24.6.14 Budget report+---------------------++The ‘--budget’ report type activates extra columns showing any budget+goals for each account and period. The budget goals are defined by+periodic transactions. This is useful for comparing planned and actual+income, expenses, time usage, etc.++ For example, you can take average monthly expenses in the common+expense categories to construct a minimal monthly budget:++;; Budget+~ monthly+ income $2000+ expenses:food $400+ expenses:bus $50+ expenses:movies $30+ assets:bank:checking++;; Two months worth of expenses+2017-11-01+ income $1950+ expenses:food $396+ expenses:bus $49+ expenses:movies $30+ expenses:supplies $20+ assets:bank:checking++2017-12-01+ income $2100+ expenses:food $412+ expenses:bus $53+ expenses:gifts $100+ assets:bank:checking++ You can now see a monthly budget report:++$ hledger balance -M --budget+Budget performance in 2017/11/01-2017/12/31:++ || Nov Dec +======================++====================================================+ assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++----------------------------------------------------+ || 0 [ 0] 0 [ 0] ++ This is different from a normal balance report in several ways:++ • Only accounts with budget goals during the report period are shown,+ by default.++ • In each column, in square brackets after the actual amount, budget+ goal amounts are shown, and the actual/goal percentage. (Note:+ budget goals should be in the same commodity as the actual amount.)++ • All parent accounts are always shown, even in list mode. Eg+ assets, assets:bank, and expenses above.++ • Amounts always include all subaccounts, budgeted or unbudgeted,+ even in list mode.++ This means that the numbers displayed will not always add up! Eg+above, the ‘expenses’ actual amount includes the gifts and supplies+transactions, but the ‘expenses:gifts’ and ‘expenses:supplies’ accounts+are not shown, as they have no budget amounts declared.++ This can be confusing. When you need to make things clearer, use the+‘-E/--empty’ flag, which will reveal all accounts including unbudgeted+ones, giving the full picture. Eg:++$ hledger balance -M --budget --empty+Budget performance in 2017/11/01-2017/12/31:++ || Nov Dec +======================++====================================================+ assets || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + assets:bank:checking || $-2445 [ 99% of $-2480] $-2665 [ 107% of $-2480] + expenses || $495 [ 103% of $480] $565 [ 118% of $480] + expenses:bus || $49 [ 98% of $50] $53 [ 106% of $50] + expenses:food || $396 [ 99% of $400] $412 [ 103% of $400] + expenses:gifts || 0 $100 + expenses:movies || $30 [ 100% of $30] 0 [ 0% of $30] + expenses:supplies || $20 0 + income || $1950 [ 98% of $2000] $2100 [ 105% of $2000] +----------------------++----------------------------------------------------+ || 0 [ 0] 0 [ 0] ++ You can roll over unspent budgets to next period with ‘--cumulative’:++$ hledger balance -M --budget --cumulative+Budget performance in 2017/11/01-2017/12/31:++ || Nov Dec +======================++====================================================+ assets || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + assets:bank:checking || $-2445 [ 99% of $-2480] $-5110 [ 103% of $-4960] + expenses || $495 [ 103% of $480] $1060 [ 110% of $960] + expenses:bus || $49 [ 98% of $50] $102 [ 102% of $100] + expenses:food || $396 [ 99% of $400] $808 [ 101% of $800] + expenses:movies || $30 [ 100% of $30] $30 [ 50% of $60] + income || $1950 [ 98% of $2000] $4050 [ 101% of $4000] +----------------------++----------------------------------------------------+ || 0 [ 0] 0 [ 0] ++ It’s common to limit budgets/budget reports to just expenses++hledger bal -M --budget expenses++ or just revenues and expenses (eg, using account types):++hledger bal -M --budget type:rx++ It’s also common to limit or convert them to a single currency+(‘cur:COMM’ or ‘-X COMM [--infer-market-prices]’). If showing multiple+currencies, ‘--layout bare’ or ‘--layout tall’ can help.++ For more examples and notes, see Budgeting.++* Menu:++* Budget report start date::+* Budgets and subaccounts::+* Selecting budget goals::+* Budget vs forecast::+++File: hledger.info, Node: Budget report start date, Next: Budgets and subaccounts, Up: Budget report++24.6.14.1 Budget report start date+..................................++This might be a bug, but for now: when making budget reports, it’s a+good idea to explicitly set the report’s start date to the first day of+a reporting period, because a periodic rule like ‘~ monthly’ generates+its transactions on the 1st of each month, and if your journal has no+regular transactions on the 1st, the default report start date could+exclude that budget goal, which can be a little surprising. Eg here the+default report period is just the day of 2020-01-15:++~ monthly in 2020+ (expenses:food) $500++2020-01-15+ expenses:food $400+ assets:checking++$ hledger bal expenses --budget+Budget performance in 2020-01-15:++ || 2020-01-15 +==============++============+ <unbudgeted> || $400 +--------------++------------+ || $400 ++ To avoid this, specify the budget report’s period, or at least the+start date, with ‘-b’/‘-e’/‘-p’/‘date:’, to ensure it includes the+budget goal transactions (periodic transactions) that you want. Eg,+adding ‘-b 2020/1/1’ to the above:++$ hledger bal expenses --budget -b 2020/1/1+Budget performance in 2020-01-01..2020-01-15:++ || 2020-01-01..2020-01-15 +===============++========================+ expenses:food || $400 [80% of $500] +---------------++------------------------+ || $400 [80% of $500] +++File: hledger.info, Node: Budgets and subaccounts, Next: Selecting budget goals, Prev: Budget report start date, Up: Budget report++24.6.14.2 Budgets and subaccounts+.................................++You can add budgets to any account in your account hierarchy. If you+have budgets on both parent account and some of its children, then+budget(s) of the child account(s) would be added to the budget of their+parent, much like account balances behave.++ In the most simple case this means that once you add a budget to any+account, all its parents would have budget as well.++ To illustrate this, consider the following budget:++~ monthly from 2019/01+ expenses:personal $1,000.00+ expenses:personal:electronics $100.00+ liabilities++ With this, monthly budget for electronics is defined to be $100 and+budget for personal expenses is an additional $1000, which implicitly+means that budget for both ‘expenses:personal’ and ‘expenses’ is $1100.++ Transactions in ‘expenses:personal:electronics’ will be counted both+towards its $100 budget and $1100 of ‘expenses:personal’ , and+transactions in any other subaccount of ‘expenses:personal’ would be+counted towards only towards the budget of ‘expenses:personal’.++ For example, let’s consider these transactions:++~ monthly from 2019/01+ expenses:personal $1,000.00+ expenses:personal:electronics $100.00+ liabilities++2019/01/01 Google home hub+ expenses:personal:electronics $90.00+ liabilities $-90.00++2019/01/02 Phone screen protector+ expenses:personal:electronics:upgrades $10.00+ liabilities++2019/01/02 Weekly train ticket+ expenses:personal:train tickets $153.00+ liabilities++2019/01/03 Flowers+ expenses:personal $30.00+ liabilities++ As you can see, we have transactions in+‘expenses:personal:electronics:upgrades’ and ‘expenses:personal:train+tickets’, and since both of these accounts are without explicitly+defined budget, these transactions would be counted towards budgets of+‘expenses:personal:electronics’ and ‘expenses:personal’ accordingly:++$ hledger balance --budget -M+Budget performance in 2019/01:++ || Jan +===============================++===============================+ expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + liabilities || $-283.00 [ 26% of $-1100.00] +-------------------------------++-------------------------------+ || 0 [ 0] ++ And with ‘--empty’, we can get a better picture of budget allocation+and consumption:++$ hledger balance --budget -M --empty+Budget performance in 2019/01:++ || Jan +========================================++===============================+ expenses || $283.00 [ 26% of $1100.00] + expenses:personal || $283.00 [ 26% of $1100.00] + expenses:personal:electronics || $100.00 [ 100% of $100.00] + expenses:personal:electronics:upgrades || $10.00 + expenses:personal:train tickets || $153.00 + liabilities || $-283.00 [ 26% of $-1100.00] +----------------------------------------++-------------------------------+ || 0 [ 0] +++File: hledger.info, Node: Selecting budget goals, Next: Budget vs forecast, Prev: Budgets and subaccounts, Up: Budget report++24.6.14.3 Selecting budget goals+................................++The budget report evaluates periodic transaction rules to generate+special "goal transactions", which generate the goal amounts for each+account in each report subperiod. When troubleshooting, you can use+‘print --forecast’ to show these as forecasted transactions:++$ hledger print --forecast=BUDGETREPORTPERIOD tag:generated++ By default, the budget report uses all available periodic transaction+rules to generate goals. This includes rules with a different report+interval from your report. Eg if you have daily, weekly and monthly+periodic rules, all of these will contribute to the goals in a monthly+budget report.++ You can select a subset of periodic rules by providing an argument to+the ‘--budget’ flag. ‘--budget=DESCPAT’ will match all periodic rules+whose description contains DESCPAT, a case-insensitive substring (not a+regular expression or query). This means you can give your periodic+rules descriptions (remember that two spaces are needed), and then+select from multiple budgets defined in your journal.+++File: hledger.info, Node: Budget vs forecast, Prev: Selecting budget goals, Up: Budget report++24.6.14.4 Budget vs forecast+............................++‘hledger --forecast ...’ and ‘hledger balance --budget ...’ are separate+features, though both of them use the periodic transaction rules defined+in the journal, and both of them generate temporary transactions for+reporting purposes ("forecast transactions" and "budget goal+transactions", respectively). You can use both features at the same+time if you want. Here are some differences between them, as of hledger+1.29:++ CLI:++ • –forecast is a general hledger option, usable with any command+ • –budget is a ‘balance’ command option, usable only with that+ command.++ Visibility of generated transactions:++ • forecast transactions are visible in any report, like ordinary+ transactions+ • budget goal transactions are invisible except for the goal amounts+ they produce in –budget reports.++ Periodic transaction rules:++ • –forecast uses all available periodic transaction rules+ • –budget uses all periodic rules (‘--budget’) or a selected subset+ (‘--budget=DESCPAT’)++ Period of generated transactions:++ • –forecast generates forecast transactions+ • from after the last regular transaction to the end of the+ report period (‘--forecast’)+ • or, during a specified period (‘--forecast=PERIODEXPR’)+ • possibly further restricted by a period specified in the+ periodic transaction rule+ • and always restricted within the bounds of the report period++ • –budget generates budget goal transactions+ • throughout the report period+ • possibly restricted by a period specified in the periodic+ transaction rule.+++File: hledger.info, Node: Data layout, Next: Useful balance reports, Prev: Budget report, Up: balance++24.6.15 Data layout+-------------------++The ‘--layout’ option affects how balance reports show multi-commodity+amounts and commodity symbols, which can improve readability. It can+also normalise the data for easy consumption by other programs. It has+four possible values:++ • ‘--layout=wide[,WIDTH]’: commodities are shown on a single line,+ optionally elided to WIDTH+ • ‘--layout=tall’: each commodity is shown on a separate line+ • ‘--layout=bare’: commodity symbols are in their own column, amounts+ are bare numbers+ • ‘--layout=tidy’: data is normalised to easily-consumed "tidy" form,+ with one row per data value++ Here are the ‘--layout’ modes supported by each output format; note+only CSV output supports all of them:++- txt csv html json sql+---------------------------------------+wide Y Y Y+tall Y Y Y+bare Y Y Y+tidy Y++ Examples:++ • Wide layout. With many commodities, reports can be very wide:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide+ Balance changes in 2012-01-01..2014-12-31:+ + || 2012 2013 2014 Total + ==================++====================================================================================================================================================================================================================+ Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT + ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT 70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT 70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT ++ • Limited wide layout. A width limit reduces the width, but some+ commodities will be hidden:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32+ Balance changes in 2012-01-01..2014-12-31:+ + || 2012 2013 2014 Total + ==================++===========================================================================================================================+ Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. + ------------------++---------------------------------------------------------------------------------------------------------------------------+ || 10.00 ITOT, 337.18 USD, 2 more.. 70.00 GLD, 18.00 ITOT, 3 more.. -11.00 ITOT, 3 more.. 70.00 GLD, 17.00 ITOT, 3 more.. ++ • Tall layout. Each commodity gets a new line (may be different in+ each column), and account names are repeated:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall+ Balance changes in 2012-01-01..2014-12-31:+ + || 2012 2013 2014 Total + ==================++==================================================+ Assets:US:ETrade || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + Assets:US:ETrade || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + Assets:US:ETrade || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + Assets:US:ETrade || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + Assets:US:ETrade || 18.00 VHT 294.00 VHT + ------------------++--------------------------------------------------+ || 10.00 ITOT 70.00 GLD -11.00 ITOT 70.00 GLD + || 337.18 USD 18.00 ITOT 4881.44 USD 17.00 ITOT + || 12.00 VEA -98.12 USD 14.00 VEA 5120.50 USD + || 106.00 VHT 10.00 VEA 170.00 VHT 36.00 VEA + || 18.00 VHT 294.00 VHT ++ • Bare layout. Commodity symbols are kept in one column, each+ commodity gets its own report row, account names are repeated:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare+ Balance changes in 2012-01-01..2014-12-31:+ + || Commodity 2012 2013 2014 Total + ==================++=============================================+ Assets:US:ETrade || GLD 0 70.00 0 70.00 + Assets:US:ETrade || ITOT 10.00 18.00 -11.00 17.00 + Assets:US:ETrade || USD 337.18 -98.12 4881.44 5120.50 + Assets:US:ETrade || VEA 12.00 10.00 14.00 36.00 + Assets:US:ETrade || VHT 106.00 18.00 170.00 294.00 + ------------------++---------------------------------------------+ || GLD 0 70.00 0 70.00 + || ITOT 10.00 18.00 -11.00 17.00 + || USD 337.18 -98.12 4881.44 5120.50 + || VEA 12.00 10.00 14.00 36.00 + || VHT 106.00 18.00 170.00 294.00 ++ • Bare layout also affects CSV output, which is useful for producing+ data that is easier to consume, eg for making charts:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare+ "account","commodity","balance"+ "Assets:US:ETrade","GLD","70.00"+ "Assets:US:ETrade","ITOT","17.00"+ "Assets:US:ETrade","USD","5120.50"+ "Assets:US:ETrade","VEA","36.00"+ "Assets:US:ETrade","VHT","294.00"+ "total","GLD","70.00"+ "total","ITOT","17.00"+ "total","USD","5120.50"+ "total","VEA","36.00"+ "total","VHT","294.00"++ • Tidy layout produces normalised "tidy data", where every variable+ has its own column and each row represents a single data point.+ See+ https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html+ for more. This is the easiest kind of data for other software to+ consume. Here’s how it looks:++ $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy+ "account","period","start_date","end_date","commodity","value"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"+ "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"+ "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"+ "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"+++File: hledger.info, Node: Useful balance reports, Prev: Data layout, Up: balance++24.6.16 Useful balance reports+------------------------------++Some frequently used ‘balance’ options/reports are:++ • ‘bal -M revenues expenses’+ Show revenues/expenses in each month. Also available as the+ ‘incomestatement’ command.++ • ‘bal -M -H assets liabilities’+ Show historical asset/liability balances at each month end. Also+ available as the ‘balancesheet’ command.++ • ‘bal -M -H assets liabilities equity’+ Show historical asset/liability/equity balances at each month end.+ Also available as the ‘balancesheetequity’ command.++ • ‘bal -M assets not:receivable’+ Show changes to liquid assets in each month. Also available as the+ ‘cashflow’ command.++ Also:++ • ‘bal -M expenses -2 -SA’+ Show monthly expenses summarised to depth 2 and sorted by average+ amount.++ • ‘bal -M --budget expenses’+ Show monthly expenses and budget goals.++ • ‘bal -M --valuechange investments’+ Show monthly change in market value of investment assets.++ • ‘bal investments --valuechange -D date:lastweek amt:'>1000' -STA+ [--invert]’+ Show top gainers [or losers] last week+++File: hledger.info, Node: balancesheet, Next: balancesheetequity, Prev: balance, Up: PART 4 COMMANDS++24.7 balancesheet+=================++(bs)++ This command displays a balance sheet, showing historical ending+balances of asset and liability accounts. (To see equity as well, use+the balancesheetequity command.) Amounts are shown with normal positive+sign, as in conventional financial statements.++ This report shows accounts declared with the ‘Asset’, ‘Cash’ or+‘Liability’ type (see account types). Or if no such accounts are+declared, it shows top-level accounts named ‘asset’ or ‘liability’ (case+insensitive, plurals allowed) and their subaccounts.++ Example:++$ hledger balancesheet+Balance Sheet++Assets:+ $-1 assets+ $1 bank:saving+ $-2 cash+--------------------+ $-1++Liabilities:+ $1 liabilities:debts+--------------------+ $1++Total:+--------------------+ 0++ This command is a higher-level variant of the ‘balance’ command, and+supports many of that command’s features, such as multi-period reports.+It is similar to ‘hledger balance -H assets liabilities’, but with+smarter account detection, and liabilities displayed with their sign+flipped.++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, ‘html’, and+(experimental) ‘json’.+++File: hledger.info, Node: balancesheetequity, Next: cashflow, Prev: balancesheet, Up: PART 4 COMMANDS++24.8 balancesheetequity+=======================++(bse)++ This command displays a balance sheet, showing historical ending+balances of asset, liability and equity accounts. Amounts are shown+with normal positive sign, as in conventional financial statements.++ This report shows accounts declared with the ‘Asset’, ‘Cash’,+‘Liability’ or ‘Equity’ type (see account types). Or if no such+accounts are declared, it shows top-level accounts named ‘asset’,+‘liability’ or ‘equity’ (case insensitive, plurals allowed) and their+subaccounts.++ Example:++$ hledger balancesheetequity+Balance Sheet With Equity++Assets:+ $-2 assets+ $1 bank:saving+ $-3 cash+--------------------+ $-2++Liabilities:+ $1 liabilities:debts+--------------------+ $1++Equity:+ $1 equity:owner+--------------------+ $1++Total:+--------------------+ 0++ This command is a higher-level variant of the ‘balance’ command, and+supports many of that command’s features, such as multi-period reports.+It is similar to ‘hledger balance -H assets liabilities equity’, but+with smarter account detection, and liabilities/equity displayed with+their sign flipped.++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, ‘html’, and+(experimental) ‘json’.+++File: hledger.info, Node: cashflow, Next: check, Prev: balancesheetequity, Up: PART 4 COMMANDS++24.9 cashflow+=============++(cf)++ This command displays a cashflow statement, showing the inflows and+outflows affecting "cash" (ie, liquid, easily convertible) assets.+Amounts are shown with normal positive sign, as in conventional+financial statements.++ This report shows accounts declared with the ‘Cash’ type (see account+types). Or if no such accounts are declared, it shows accounts++ • under a top-level account named ‘asset’ (case insensitive, plural+ allowed)+ • whose name contains some variation of ‘cash’, ‘bank’, ‘checking’ or+ ‘saving’.++ More precisely: all accounts matching this case insensitive regular+expression:++ ‘^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)’++ and their subaccounts.++ An example cashflow report:++$ hledger cashflow+Cashflow Statement++Cash flows:+ $-1 assets+ $1 bank:saving+ $-2 cash+--------------------+ $-1++Total:+--------------------+ $-1++ This command is a higher-level variant of the ‘balance’ command, and+supports many of that command’s features, such as multi-period reports.+It is similar to ‘hledger balance assets not:fixed not:investment+not:receivable’, but with smarter account detection.++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, ‘html’, and+(experimental) ‘json’.+++File: hledger.info, Node: check, Next: close, Prev: cashflow, Up: PART 4 COMMANDS++24.10 check+===========++Check for various kinds of errors in your data.++ hledger provides a number of built-in error checks to help prevent+problems in your data. Some of these are run automatically; or, you can+use this ‘check’ command to run them on demand, with no output and a+zero exit code if all is well. Specify their names (or a prefix) as+argument(s).++ Some examples:++hledger check # basic checks+hledger check -s # basic + strict checks+hledger check ordereddates payees # basic + two other checks++ If you are an Emacs user, you can also configure flycheck-hledger to+run these checks, providing instant feedback as you edit the journal.++ Here are the checks currently available:++* Menu:++* Basic checks::+* Strict checks::+* Other checks::+* Custom checks::+* More about specific checks::+++File: hledger.info, Node: Basic checks, Next: Strict checks, Up: check++24.10.1 Basic checks+--------------------++These checks are always run automatically, by (almost) all hledger+commands, including ‘check’:++ • *parseable* - data files are well-formed and can be successfully+ parsed++ • *balancedwithautoconversion* - all transactions are balanced,+ inferring missing amounts where necessary, and possibly converting+ commodities using costs or automatically-inferred costs++ • *assertions* - all balance assertions in the journal are passing.+ (This check can be disabled with ‘-I’/‘--ignore-assertions’.)+++File: hledger.info, Node: Strict checks, Next: Other checks, Prev: Basic checks, Up: check++24.10.2 Strict checks+---------------------++These additional checks are run when the ‘-s’/‘--strict’ (strict mode)+flag is used. Or, they can be run by giving their names as arguments to+‘check’:++ • *accounts* - all account names used by transactions have been+ declared++ • *commodities* - all commodity symbols used have been declared++ • *balancednoautoconversion* - transactions are balanced, possibly+ using explicit costs but not inferred ones+++File: hledger.info, Node: Other checks, Next: Custom checks, Prev: Strict checks, Up: check++24.10.3 Other checks+--------------------++These checks can be run only by giving their names as arguments to+‘check’. They are more specialised and not desirable for everyone,+therefore optional:++ • *ordereddates* - transactions are ordered by date within each file++ • *payees* - all payees used by transactions have been declared++ • *recentassertions* - all accounts with balance assertions have a+ balance assertion no more than 7 days before their latest posting++ • *tags* - all tags used by transactions have been declared++ • *uniqueleafnames* - all account leaf names are unique+++File: hledger.info, Node: Custom checks, Next: More about specific checks, Prev: Other checks, Up: check++24.10.4 Custom checks+---------------------++A few more checks are are available as separate add-on commands, in+https://github.com/simonmichael/hledger/tree/master/bin:++ • *hledger-check-tagfiles* - all tag values containing / (a forward+ slash) exist as file paths++ • *hledger-check-fancyassertions* - more complex balance assertions+ are passing++ You could make similar scripts to perform your own custom checks.+See: Cookbook -> Scripting.+++File: hledger.info, Node: More about specific checks, Prev: Custom checks, Up: check++24.10.5 More about specific checks+----------------------------------++‘hledger check recentassertions’ will complain if any balance-asserted+account does not have a balance assertion within 7 days before its+latest posting. This aims to prevent the situation where you are+regularly updating your journal, but forgetting to check your balances+against the real world, then one day must dig back through months of+data to find an error. It assumes that adding a balance assertion+requires/reminds you to check the real-world balance. That may not be+true if you auto-generate balance assertions from bank data; in that+case, I recommend to import transactions uncleared, then use the+manual-review-and-mark-cleared phase as a reminder to check the latest+assertions against real-world balances.+++File: hledger.info, Node: close, Next: codes, Prev: check, Up: PART 4 COMMANDS++24.11 close+===========++‘close [--retain | --migrate | --open] [QUERY]’++ By default: prints a transaction that zeroes out ("closes") all+accounts, transferring their balances to an equity account. Query+arguments can be added to override the accounts selection. Three other+modes are supported:++ ‘--retain’: prints a transaction closing revenue and expense+balances. This is traditionally done by businesses at the end of each+accounting period; it is less necessary in personal and computer-based+accounting, but it can help balance the accounting equation A=L+E.++ ‘--migrate’: prints a transaction to close asset, liability and most+equity balances, and another transaction to re-open them. This can be+useful when starting a new file (for performance or data protection).+Adding the closing transaction to the old file allows old and new files+to be combined.++ ‘--open’: as above, but prints just the opening transaction. This+can be useful for starting a new file, leaving the old file unchanged.+Similar to Ledger’s equity command.++ You can change the equity account name with ‘--close-acct ACCT’. It+defaults to ‘equity:retained earnings’ with ‘--retain’, or+‘equity:opening/closing balances’ otherwise.++ You can change the transaction description(s) with ‘--close-desc+'DESC'’ and ‘--open-desc 'DESC'’. It defaults to ‘retain earnings’ with+‘--retain’, or ‘closing balances’ and ‘opening balances’ otherwise.++ Just one posting to the equity account will be used by default, with+an implicit amount.++ With ‘--x/--explicit’ the amount will be shown explicitly, and if it+involves multiple commodities, a separate posting will be generated for+each commodity.++ With ‘--interleaved’, each equity posting is shown next to the+corresponding source/destination posting.++ The default closing date is yesterday or the journal’s end date,+whichever is later. You can change this by specifying a report end+date; the last day of the report period will be the closing date. Eg+‘-e 2022’ means "close on 2022-12-31".++ The default closing date is yesterday, or the journal’s end date,+whichever is later. You can change this by specifying a report end+date; (The report start date does not matter.) The last day of the+report period will be the closing date; eg ‘-e 2022’ means "close on+2022-12-31". The opening date is always the day after the closing date.++* Menu:++* close and costs::+* close and balance assertions::+* Example retain earnings::+* Example migrate balances to a new file::+* Example excluding closing/opening transactions::+++File: hledger.info, Node: close and costs, Next: close and balance assertions, Up: close++24.11.1 close and costs+-----------------------++With ‘--show-costs’, any amount costs are shown, with separate postings+for each cost. (This currently the best way to view investment assets,+showing lots and cost bases.) If you have many currency conversion or+investment transactions, it can generate very large journal entries.+++File: hledger.info, Node: close and balance assertions, Next: Example retain earnings, Prev: close and costs, Up: close++24.11.2 close and balance assertions+------------------------------------++Balance assertions will be generated, verifying that the accounts have+been reset to zero (and then restored to their previous balances, if+there is an opening transaction).++ These provide useful error checking, but you can ignore them+temporarily with ‘-I’, or remove them if you prefer.++ You probably should avoid filtering transactions by status or+realness (‘-C’, ‘-R’, ‘status:’), or generating postings (‘--auto’),+with this command, since the balance assertions would depend on these.++ Note custom posting dates spanning the file boundary will disrupt the+balance assertions:++2023-12-30 a purchase made in december, cleared in january+ expenses:food 5+ assets:bank:checking -5 ; date: 2023-01-02++ To solve that you can transfer the money to and from a temporary+account, in effect splitting the multi-day transaction into two+single-day transactions:++; in 2022.journal:+2022-12-30 a purchase made in december, cleared in january+ expenses:food 5+ equity:pending -5++; in 2023.journal:+2023-01-02 last year's transaction cleared+ equity:pending 5 = 0+ assets:bank:checking -5+++File: hledger.info, Node: Example retain earnings, Next: Example migrate balances to a new file, Prev: close and balance assertions, Up: close++24.11.3 Example: retain earnings+--------------------------------++Record 2022’s revenues/expenses as retained earnings on 2022-12-31,+appending the generated transaction to the journal:++$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal++ Now 2022’s income statement will show only zeroes. To see it again,+exclude the retain transaction. Eg:++$ hledger -f 2022.journal is not:desc:'retain earnings'+++File: hledger.info, Node: Example migrate balances to a new file, Next: Example excluding closing/opening transactions, Prev: Example retain earnings, Up: close++24.11.4 Example: migrate balances to a new file+-----------------------------------------------++Close assets/liabilities/equity on 2022-12-31 and re-open them on+2023-01-01:++$ hledger close --migrate -f 2022.journal -p 2022+# copy/paste the closing transaction to the end of 2022.journal+# copy/paste the opening transaction to the start of 2023.journal++ Now 2022’s balance sheet will show only zeroes, indicating a balanced+accounting equation. (Unless you are using @/@@ notation - in that+case, try adding –infer-equity.) To see it again, exclude the closing+transaction. Eg:++$ hledger -f 2022.journal bs not:desc:'closing balances'+++File: hledger.info, Node: Example excluding closing/opening transactions, Prev: Example migrate balances to a new file, Up: close++24.11.5 Example: excluding closing/opening transactions+-------------------------------------------------------++When combining many files for multi-year reports, the closing/opening+transactions cause some noise in reports like ‘print’ and ‘register’.+You can exclude them as shown above, but ‘not:desc:...’ could be+fragile, and also you will need to avoid excluding the very first+opening transaction, which can be awkward. Here is a way to do it,+using tags: add ‘clopen:’ tags to all opening/closing balances+transactions except the first, like this:++; 2021.journal+2021-06-01 first opening balances+...+2021-12-31 closing balances ; clopen:2022+...++; 2022.journal+2022-01-01 opening balances ; clopen:2022+...+2022-12-31 closing balances ; clopen:2023+...++; 2023.journal+2023-01-01 opening balances ; clopen:2023+...++ Now, assuming a combined journal like:++; all.journal+include 2021.journal+include 2022.journal+include 2023.journal++ The ‘clopen:’ tag can exclude all but the first opening transaction.+To show a clean multi-year checking register:++$ hledger -f all.journal areg checking not:tag:clopen++ And the year values allow more precision. To show 2022’s year-end+balance sheet:++$ hledger -f all.journal bs -e2023 not:tag:clopen=2023+++File: hledger.info, Node: codes, Next: commodities, Prev: close, Up: PART 4 COMMANDS++24.12 codes+===========++List the codes seen in transactions, in the order parsed.++ This command prints the value of each transaction’s code field, in+the order transactions were parsed. The transaction code is an optional+value written in parentheses between the date and description, often+used to store a cheque number, order number or similar.++ Transactions aren’t required to have a code, and missing or empty+codes will not be shown by default. With the ‘-E’/‘--empty’ flag, they+will be printed as blank lines.++ You can add a query to select a subset of transactions.++ Examples:++2022/1/1 (123) Supermarket + Food $5.00+ Checking ++2022/1/2 (124) Post Office+ Postage $8.32+ Checking++2022/1/3 Supermarket+ Food $11.23+ Checking ++2022/1/4 (126) Post Office+ Postage $3.21+ Checking++$ hledger codes+123+124+126++$ hledger codes -E+123+124++126+++File: hledger.info, Node: commodities, Next: descriptions, Prev: codes, Up: PART 4 COMMANDS++24.13 commodities+=================++List all commodity/currency symbols used or declared in the journal.+++File: hledger.info, Node: descriptions, Next: diff, Prev: commodities, Up: PART 4 COMMANDS++24.14 descriptions+==================++List the unique descriptions that appear in transactions.++ This command lists the unique descriptions that appear in+transactions, in alphabetic order. You can add a query to select a+subset of transactions.++ Example:++$ hledger descriptions+Store Name+Gas Station | Petrol+Person A+++File: hledger.info, Node: diff, Next: files, Prev: descriptions, Up: PART 4 COMMANDS++24.15 diff+==========++Compares a particular account’s transactions in two input files. It+shows any transactions to this account which are in one file but not in+the other.++ More precisely, for each posting affecting this account in either+file, it looks for a corresponding posting in the other file which posts+the same amount to the same account (ignoring date, description, etc.)+Since postings not transactions are compared, this also works when+multiple bank transactions have been combined into a single journal+entry.++ This is useful eg if you have downloaded an account’s transactions+from your bank (eg as CSV data). When hledger and your bank disagree+about the account balance, you can compare the bank data with your+journal to find out the cause.++ Examples:++$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro +These transactions are in the first file only:++2014/01/01 Opening Balances+ assets:bank:giro EUR ...+ ...+ equity:opening balances EUR -...++These transactions are in the second file only:+++File: hledger.info, Node: files, Next: help, Prev: diff, Up: PART 4 COMMANDS++24.16 files+===========++List all files included in the journal. With a REGEX argument, only+file names matching the regular expression (case sensitive) are shown.+++File: hledger.info, Node: help, Next: import, Prev: files, Up: PART 4 COMMANDS++24.17 help+==========++Show the hledger user manual in the terminal, with ‘info’, ‘man’, or a+pager. With a TOPIC argument, open it at that topic if possible. TOPIC+can be any heading in the manual, or a heading prefix, case insensitive.+Eg: ‘commands’, ‘print’, ‘forecast’, ‘journal’, ‘amount’, ‘"auto+postings"’.++ This command shows the hledger manual built in to your hledger+version. It can be useful when offline, or when you prefer the terminal+to a web browser, or when the appropriate hledger manual or viewing+tools are not installed on your system.++ By default it chooses the best viewer found in $PATH (preferring info+since the hledger manual is large). You can select a particular viewer+with the ‘-i’, ‘-m’, or ‘-p’ flags.++ Examples++$ hledger help --help # show how the help command works+$ hledger help # show the hledger manual with info, man or $PAGER+$ hledger help journal # show the journal topic in the hledger manual+++File: hledger.info, Node: import, Next: incomestatement, Prev: help, Up: PART 4 COMMANDS++24.18 import+============++Read new transactions added to each FILE since last run, and add them to+the journal. Or with –dry-run, just print the transactions that would+be added. Or with –catchup, just mark all of the FILEs’ transactions as+imported, without actually importing any.++ This command may append new transactions to the main journal file+(which should be in journal format). Existing transactions are not+changed. This is one of the few hledger commands that writes to the+journal file (see also ‘add’).++ Unlike other hledger commands, with ‘import’ the journal file is an+output file, and will be modified, though only by appending (existing+data will not be changed). The input files are specified as arguments,+so to import one or more CSV files to your main journal, you will run+‘hledger import bank.csv’ or perhaps ‘hledger import *.csv’.++ Note you can import from any file format, though CSV files are the+most common import source, and these docs focus on that case.++* Menu:++* Deduplication::+* Import testing::+* Importing balance assignments::+* Commodity display styles::+++File: hledger.info, Node: Deduplication, Next: Import testing, Up: import++24.18.1 Deduplication+---------------------++As a convenience ‘import’ does _deduplication_ while reading+transactions. This does not mean "ignore transactions that look the+same", but rather "ignore transactions that have been seen before".+This is intended for when you are periodically importing foreign data+which may contain already-imported transactions. So eg, if every day+you download bank CSV files containing redundant data, you can safely+run ‘hledger import bank.csv’ and only new transactions will be+imported. (‘import’ is idempotent.)++ Since the items being read (CSV records, eg) often do not come with+unique identifiers, hledger detects new transactions by date, assuming+that:++ 1. new items always have the newest dates+ 2. item dates do not change across reads+ 3. and items with the same date remain in the same relative order+ across reads.++ These are often true of CSV files representing transactions, or true+enough so that it works pretty well in practice. 1 is important, but+violations of 2 and 3 amongst the old transactions won’t matter (and if+you import often, the new transactions will be few, so less likely to be+the ones affected).++ hledger remembers the latest date processed in each input file by+saving a hidden ".latest" state file in the same directory. Eg when+reading ‘finance/bank.csv’, it will look for and update the+‘finance/.latest.bank.csv’ state file. The format is simple: one or+more lines containing the same ISO-format date (YYYY-MM-DD), meaning "I+have processed transactions up to this date, and this many of them on+that date." Normally you won’t see or manipulate these state files+yourself. But if needed, you can delete them to reset the state (making+all transactions "new"), or you can construct them to "catch up" to a+certain date.++ Note deduplication (and updating of state files) can also be done by+‘print --new’, but this is less often used.+++File: hledger.info, Node: Import testing, Next: Importing balance assignments, Prev: Deduplication, Up: import++24.18.2 Import testing+----------------------++With ‘--dry-run’, the transactions that will be imported are printed to+the terminal, without updating your journal or state files. The output+is valid journal format, like the print command, so you can re-parse it.+Eg, to see any importable transactions which CSV rules have not+categorised:++$ hledger import --dry bank.csv | hledger -f- -I print unknown++ or (live updating):++$ ls bank.csv* | entr bash -c 'echo ====; hledger import --dry bank.csv | hledger -f- -I print unknown'++ Note: when importing from multiple files at once, it’s currently+possible for some .latest files to be updated successfully, while the+actual import fails because of a problem in one of the files, leaving+them out of sync (and causing some transactions to be missed). To+prevent this, do a –dry-run first and fix any problems before the real+import.+++File: hledger.info, Node: Importing balance assignments, Next: Commodity display styles, Prev: Import testing, Up: import++24.18.3 Importing balance assignments+-------------------------------------++Entries added by import will have their posting amounts made explicit+(like ‘hledger print -x’). This means that any balance assignments in+imported files must be evaluated; but, imported files don’t get to see+the main file’s account balances. As a result, importing entries with+balance assignments (eg from an institution that provides only balances+and not posting amounts) will probably generate incorrect posting+amounts. To avoid this problem, use print instead of import:++$ hledger print IMPORTFILE [--new] >> $LEDGER_FILE++ (If you think import should leave amounts implicit like print does,+please test it and send a pull request.)+++File: hledger.info, Node: Commodity display styles, Prev: Importing balance assignments, Up: import++24.18.4 Commodity display styles+--------------------------------++Imported amounts will be formatted according to the canonical commodity+styles (declared or inferred) in the main journal file.+++File: hledger.info, Node: incomestatement, Next: notes, Prev: import, Up: PART 4 COMMANDS++24.19 incomestatement+=====================++(is)++ This command displays an income statement, showing revenues and+expenses during one or more periods. Amounts are shown with normal+positive sign, as in conventional financial statements.++ This report shows accounts declared with the ‘Revenue’ or ‘Expense’+type (see account types). Or if no such accounts are declared, it shows+top-level accounts named ‘revenue’ or ‘income’ or ‘expense’ (case+insensitive, plurals allowed) and their subaccounts.++ Example:++$ hledger incomestatement+Income Statement++Revenues:+ $-2 income+ $-1 gifts+ $-1 salary+--------------------+ $-2++Expenses:+ $2 expenses+ $1 food+ $1 supplies+--------------------+ $2++Total:+--------------------+ 0++ This command is a higher-level variant of the ‘balance’ command, and+supports many of that command’s features, such as multi-period reports.+It is similar to ‘hledger balance '(revenues|income)' expenses’, but+with smarter account detection, and revenues/income displayed with their+sign flipped.++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, ‘html’, and+(experimental) ‘json’.+++File: hledger.info, Node: notes, Next: payees, Prev: incomestatement, Up: PART 4 COMMANDS++24.20 notes+===========++List the unique notes that appear in transactions.++ This command lists the unique notes that appear in transactions, in+alphabetic order. You can add a query to select a subset of+transactions. The note is the part of the transaction description after+a | character (or if there is no |, the whole description).++ Example:++$ hledger notes+Petrol+Snacks+++File: hledger.info, Node: payees, Next: prices, Prev: notes, Up: PART 4 COMMANDS++24.21 payees+============++List the unique payee/payer names that appear in transactions.++ This command lists unique payee/payer names which have been declared+with payee directives (–declared), used in transaction descriptions+(–used), or both (the default).++ The payee/payer is the part of the transaction description before a |+character (or if there is no |, the whole description).++ You can add query arguments to select a subset of transactions. This+implies –used.++ Example:++$ hledger payees+Store Name+Gas Station+Person A+++File: hledger.info, Node: prices, Next: print, Prev: payees, Up: PART 4 COMMANDS++24.22 prices+============++Print market price directives from the journal. With+–infer-market-prices, generate additional market prices from costs.+With –infer-reverse-prices, also generate market prices by inverting+known prices. Prices can be filtered by a query. Price amounts are+displayed with their full precision.+++File: hledger.info, Node: print, Next: register, Prev: prices, Up: PART 4 COMMANDS++24.23 print+===========++Show transaction journal entries, sorted by date.++ The print command displays full journal entries (transactions) from+the journal file, sorted by date (or with ‘--date2’, by secondary date).++ Amounts are shown mostly normalised to commodity display style, eg+the placement of commodity symbols will be consistent. All of their+decimal places are shown, as in the original journal entry (with one+alteration: in some cases trailing zeroes are added.)++ Amounts are shown right-aligned within each transaction (but not+across all transactions).++ Directives and inter-transaction comments are not shown, currently.+This means the print command is somewhat lossy, and if you are using it+to reformat your journal you should take care to also copy over the+directives and file-level comments.++ Eg:++$ hledger print+2008/01/01 income+ assets:bank:checking $1+ income:salary $-1++2008/06/01 gift+ assets:bank:checking $1+ income:gifts $-1++2008/06/02 save+ assets:bank:saving $1+ assets:bank:checking $-1++2008/06/03 * eat & shop+ expenses:food $1+ expenses:supplies $1+ assets:cash $-2++2008/12/31 * pay off+ liabilities:debts $1+ assets:bank:checking $-1++ print’s output is usually a valid hledger journal, and you can+process it again with a second hledger command. This can be useful for+certain kinds of search, eg:++# Show running total of food expenses paid from cash.+# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.+$ hledger print assets:cash | hledger -f- -I reg expenses:food++ There are some situations where print’s output can become+unparseable:++ • Valuation affects posting amounts but not balance assertion or+ balance assignment amounts, potentially causing those to fail.+ • Auto postings can generate postings with too many missing amounts.+ • Account aliases can generate bad account names.++ Normally, the journal entry’s explicit or implicit amount style is+preserved. For example, when an amount is omitted in the journal, it+will not appear in the output. Similarly, when a cost is implied but+not written, it will not appear in the output. You can use the+‘-x’/‘--explicit’ flag to make all amounts and costs explicit, which can+be useful for troubleshooting or for making your journal more readable+and robust against data entry errors. ‘-x’ is also implied by using any+of ‘-B’,‘-V’,‘-X’,‘--value’.++ Note, ‘-x’/‘--explicit’ will cause postings with a multi-commodity+amount (these can arise when a multi-commodity transaction has an+implicit amount) to be split into multiple single-commodity postings,+keeping the output parseable.++ With ‘-B’/‘--cost’, amounts with costs are converted to cost using+that price. This can be used for troubleshooting.++ With ‘-m DESC’/‘--match=DESC’, print does a fuzzy search for one+recent transaction whose description is most similar to DESC. DESC+should contain at least two characters. If there is no similar-enough+match, no transaction will be shown and the program exit code will be+non-zero.++ With ‘--new’, hledger prints only transactions it has not seen on a+previous run. This uses the same deduplication system as the ‘import’+command. (See import’s docs for details.)++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, and+(experimental) ‘json’ and ‘sql’.++ Here’s an example of print’s CSV output:++$ hledger print -Ocsv+"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"+"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""+"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""+"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""+"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""+"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""+"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""+"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""+"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""+"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""+"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""+"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""++ • There is one CSV record per posting, with the parent transaction’s+ fields repeated.+ • The "txnidx" (transaction index) field shows which postings belong+ to the same transaction. (This number might change if transactions+ are reordered within the file, files are parsed/included in a+ different order, etc.)+ • The amount is separated into "commodity" (the symbol) and "amount"+ (numeric quantity) fields.+ • The numeric amount is repeated in either the "credit" or "debit"+ column, for convenience. (Those names are not accurate in the+ accounting sense; it just puts negative amounts under credit and+ zero or greater amounts under debit.)+++File: hledger.info, Node: register, Next: rewrite, Prev: print, Up: PART 4 COMMANDS++24.24 register+==============++(reg)++ Show postings and their running total.++ The register command displays matched postings, across all accounts,+in date order, with their running total or running historical balance.+(See also the ‘aregister’ command, which shows matched transactions in a+specific account.)++ register normally shows line per posting, but note that+multi-commodity amounts will occupy multiple lines (one line per+commodity).++ It is typically used with a query selecting a particular account, to+see that account’s activity:++$ hledger register checking+2008/01/01 income assets:bank:checking $1 $1+2008/06/01 gift assets:bank:checking $1 $2+2008/06/02 save assets:bank:checking $-1 $1+2008/12/31 pay off assets:bank:checking $-1 0++ With ‘--date2’, it shows and sorts by secondary date instead.++ For performance reasons, column widths are chosen based on the first+1000 lines; this means unusually wide values in later lines can cause+visual discontinuities as column widths are adjusted. If you want to+ensure perfect alignment, at the cost of more time and memory, use the+‘--align-all’ flag.++ The ‘--historical’/‘-H’ flag adds the balance from any undisplayed+prior postings to the running total. This is useful when you want to+see only recent activity, with a historically accurate running balance:++$ hledger register checking -b 2008/6 --historical+2008/06/01 gift assets:bank:checking $1 $2+2008/06/02 save assets:bank:checking $-1 $1+2008/12/31 pay off assets:bank:checking $-1 0++ The ‘--depth’ option limits the amount of sub-account detail+displayed.++ The ‘--average’/‘-A’ flag shows the running average posting amount+instead of the running total (so, the final number displayed is the+average for the whole report period). This flag implies ‘--empty’ (see+below). It is affected by ‘--historical’. It works best when showing+just one account and one commodity.++ The ‘--related’/‘-r’ flag shows the _other_ postings in the+transactions of the postings which would normally be shown.++ The ‘--invert’ flag negates all amounts. For example, it can be used+on an income account where amounts are normally displayed as negative+numbers. It’s also useful to show postings on the checking account+together with the related account:++$ hledger register --related --invert assets:checking++ With a reporting interval, register shows summary postings, one per+interval, aggregating the postings to each account:++$ hledger register --monthly income+2008/01 income:salary $-1 $-1+2008/06 income:gifts $-1 $-2++ Periods with no activity, and summary postings with a zero amount,+are not shown by default; use the ‘--empty’/‘-E’ flag to see them:++$ hledger register --monthly income -E+2008/01 income:salary $-1 $-1+2008/02 0 $-1+2008/03 0 $-1+2008/04 0 $-1+2008/05 0 $-1+2008/06 income:gifts $-1 $-2+2008/07 0 $-2+2008/08 0 $-2+2008/09 0 $-2+2008/10 0 $-2+2008/11 0 $-2+2008/12 0 $-2++ Often, you’ll want to see just one line per interval. The ‘--depth’+option helps with this, causing subaccounts to be aggregated:++$ hledger register --monthly assets --depth 1h+2008/01 assets $1 $1+2008/06 assets $-1 0+2008/12 assets $-1 $-1++ Note when using report intervals, if you specify start/end dates+these will be adjusted outward if necessary to contain a whole number of+intervals. This ensures that the first and last intervals are full+length and comparable to the others in the report.++ With ‘-m DESC’/‘--match=DESC’, register does a fuzzy search for one+recent posting whose description is most similar to DESC. DESC should+contain at least two characters. If there is no similar-enough match,+no posting will be shown and the program exit code will be non-zero.++* Menu:++* Custom register output::+++File: hledger.info, Node: Custom register output, Up: register++24.24.1 Custom register output+------------------------------++register uses the full terminal width by default, except on windows.+You can override this by setting the ‘COLUMNS’ environment variable (not+a bash shell variable) or by using the ‘--width’/‘-w’ option.++ The description and account columns normally share the space equally+(about half of (width - 40) each). You can adjust this by adding a+description width as part of –width’s argument, comma-separated:+‘--width W,D’ . Here’s a diagram (won’t display correctly in –help):++<--------------------------------- width (W) ---------------------------------->+date (10) description (D) account (W-41-D) amount (12) balance (12)+DDDDDDDDDD dddddddddddddddddddd aaaaaaaaaaaaaaaaaaa AAAAAAAAAAAA AAAAAAAAAAAA++ and some examples:++$ hledger reg # use terminal width (or 80 on windows)+$ hledger reg -w 100 # use width 100+$ COLUMNS=100 hledger reg # set with one-time environment variable+$ export COLUMNS=100; hledger reg # set till session end (or window resize)+$ hledger reg -w 100,40 # set overall width 100, description width 40+$ hledger reg -w $COLUMNS,40 # use terminal width, & description width 40++ This command also supports the output destination and output format+options The output formats supported are ‘txt’, ‘csv’, and+(experimental) ‘json’.+++File: hledger.info, Node: rewrite, Next: roi, Prev: register, Up: PART 4 COMMANDS++24.25 rewrite+=============++Print all transactions, rewriting the postings of matched transactions.+For now the only rewrite available is adding new postings, like print+–auto.++ This is a start at a generic rewriter of transaction entries. It+reads the default journal and prints the transactions, like print, but+adds one or more specified postings to any transactions matching QUERY.+The posting amounts can be fixed, or a multiplier of the existing+transaction’s first posting amount.++ Examples:++$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax) *.33 ; income tax' --add-posting '(reserve:gifts) $100'+$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts) *-1"'+$ hledger-rewrite.hs -f rewrites.hledger++ rewrites.hledger may consist of entries like:++= ^income amt:<0 date:2017+ (liabilities:tax) *0.33 ; tax on income+ (reserve:grocery) *0.25 ; reserve 25% for grocery+ (reserve:) *0.25 ; reserve 25% for grocery++ Note the single quotes to protect the dollar sign from bash, and the+two spaces between account and amount.++ More:++$ hledger rewrite -- [QUERY] --add-posting "ACCT AMTEXPR" ...+$ hledger rewrite -- ^income --add-posting '(liabilities:tax) *.33'+$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts) *-1"'+$ hledger rewrite -- ^income --add-posting '(budget:foreign currency) *0.25 JPY; diversify'++ Argument for ‘--add-posting’ option is a usual posting of transaction+with an exception for amount specification. More precisely, you can use+‘'*'’ (star symbol) before the amount to indicate that that this is a+factor for an amount of original matched posting. If the amount+includes a commodity name, the new posting amount will be in the new+commodity; otherwise, it will be in the matched posting amount’s+commodity.++* Menu:++* Re-write rules in a file::+* Diff output format::+* rewrite vs print --auto::+++File: hledger.info, Node: Re-write rules in a file, Next: Diff output format, Up: rewrite++24.25.1 Re-write rules in a file+--------------------------------++During the run this tool will execute so called "Automated Transactions"+found in any journal it process. I.e instead of specifying this+operations in command line you can put them in a journal file.++$ rewrite-rules.journal++ Make contents look like this:++= ^income+ (liabilities:tax) *.33++= expenses:gifts+ budget:gifts *-1+ assets:budget *1++ Note that ‘'='’ (equality symbol) that is used instead of date in+transactions you usually write. It indicates the query by which you+want to match the posting to add new ones.++$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal++ This is something similar to the commands pipeline:++$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax) *.33' \+ | hledger rewrite -- -f - expenses:gifts --add-posting 'budget:gifts *-1' \+ --add-posting 'assets:budget *1' \+ > rewritten-tidy-output.journal++ It is important to understand that relative order of such entries in+journal is important. You can re-use result of previously added+postings.+++File: hledger.info, Node: Diff output format, Next: rewrite vs print --auto, Prev: Re-write rules in a file, Up: rewrite++24.25.2 Diff output format+--------------------------++To use this tool for batch modification of your journal files you may+find useful output in form of unified diff.++$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax) *.33'++ Output might look like:++--- /tmp/examples/sample.journal++++ /tmp/examples/sample.journal+@@ -18,3 +18,4 @@+ 2008/01/01 income+- assets:bank:checking $1++ assets:bank:checking $1+ income:salary++ (liabilities:tax) 0+@@ -22,3 +23,4 @@+ 2008/06/01 gift+- assets:bank:checking $1++ assets:bank:checking $1+ income:gifts++ (liabilities:tax) 0++ If you’ll pass this through ‘patch’ tool you’ll get transactions+containing the posting that matches your query be updated. Note that+multiple files might be update according to list of input files+specified via ‘--file’ options and ‘include’ directives inside of these+files.++ Be careful. Whole transaction being re-formatted in a style of+output from ‘hledger print’.++ See also:++ https://github.com/simonmichael/hledger/issues/99+++File: hledger.info, Node: rewrite vs print --auto, Prev: Diff output format, Up: rewrite++24.25.3 rewrite vs. print –auto+-------------------------------++This command predates print –auto, and currently does much the same+thing, but with these differences:++ • with multiple files, rewrite lets rules in any file affect all+ other files. print –auto uses standard directive scoping; rules+ affect only child files.++ • rewrite’s query limits which transactions can be rewritten; all are+ printed. print –auto’s query limits which transactions are+ printed.++ • rewrite applies rules specified on command line or in the journal.+ print –auto applies rules specified in the journal.+++File: hledger.info, Node: roi, Next: stats, Prev: rewrite, Up: PART 4 COMMANDS++24.26 roi+=========++Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on+your investments.++ At a minimum, you need to supply a query (which could be just an+account name) to select your investment(s) with ‘--inv’, and another+query to identify your profit and loss transactions with ‘--pnl’.++ If you do not record changes in the value of your investment+manually, or do not require computation of time-weighted return (TWR),+‘--pnl’ could be an empty query (‘--pnl ""’ or ‘--pnl STR’ where ‘STR’+does not match any of your accounts).++ This command will compute and display the internalized rate of return+(IRR) and time-weighted rate of return (TWR) for your investments for+the time period requested. Both rates of return are annualized before+display, regardless of the length of reporting interval.++ Price directives will be taken into account if you supply appropriate+‘--cost’ or ‘--value’ flags (see VALUATION).++ Note, in some cases this report can fail, for these reasons:++ • Error (NotBracketed): No solution for Internal Rate of Return+ (IRR). Possible causes: IRR is huge (>1000000%), balance of+ investment becomes negative at some point in time.+ • Error (SearchFailed): Failed to find solution for Internal Rate of+ Return (IRR). Either search does not converge to a solution, or+ converges too slowly.++ Examples:++ • Using roi to compute total return of investment in stocks:+ https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger++ • Cookbook > Return on Investment: https://hledger.org/roi.html++* Menu:++* Spaces and special characters in --inv and --pnl::+* Semantics of --inv and --pnl::+* IRR and TWR explained::+++File: hledger.info, Node: Spaces and special characters in --inv and --pnl, Next: Semantics of --inv and --pnl, Up: roi++24.26.1 Spaces and special characters in ‘--inv’ and+----------------------------------------------------++‘--pnl’ Note that ‘--inv’ and ‘--pnl’’s argument is a query, and queries+could have several space-separated terms (see QUERIES).++ To indicate that all search terms form single command-line argument,+you will need to put them in quotes (see Special characters):++$ hledger roi --inv 'term1 term2 term3 ...'++ If any query terms contain spaces themselves, you will need an extra+level of nested quoting, eg:++$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"+++File: hledger.info, Node: Semantics of --inv and --pnl, Next: IRR and TWR explained, Prev: Spaces and special characters in --inv and --pnl, Up: roi++24.26.2 Semantics of ‘--inv’ and ‘--pnl’+----------------------------------------++Query supplied to ‘--inv’ has to match all transactions that are related+to your investment. Transactions not matching ‘--inv’ will be ignored.++ In these transactions, ROI will conside postings that match ‘--inv’+to be "investment postings" and other postings (not matching ‘--inv’)+will be sorted into two categories: "cash flow" and "profit and loss",+as ROI needs to know which part of the investment value is your+contributions and which is due to the return on investment.++ • "Cash flow" is depositing or withdrawing money, buying or selling+ assets, or otherwise converting between your investment commodity+ and any other commodity. Example:++ 2019-01-01 Investing in Snake Oil+ assets:cash -$100+ investment:snake oil+ + 2020-01-01 Selling my Snake Oil+ assets:cash $10+ investment:snake oil = 0++ • "Profit and loss" is change in the value of your investment:++ 2019-06-01 Snake Oil falls in value+ investment:snake oil = $57+ equity:unrealized profit or loss++ All non-investment postings are assumed to be "cash flow", unless+they match ‘--pnl’ query. Changes in value of your investment due to+"profit and loss" postings will be considered as part of your investment+return.++ Example: if you use ‘--inv snake --pnl equity:unrealized’, then+postings in the example below would be classifed as:++2019-01-01 Snake Oil #1+ assets:cash -$100 ; cash flow posting+ investment:snake oil ; investment posting++2019-03-01 Snake Oil #2+ equity:unrealized pnl -$100 ; profit and loss posting+ snake oil ; investment posting++2019-07-01 Snake Oil #3+ equity:unrealized pnl ; profit and loss posting+ cash -$100 ; cash flow posting+ snake oil $50 ; investment posting+++File: hledger.info, Node: IRR and TWR explained, Prev: Semantics of --inv and --pnl, Up: roi++24.26.3 IRR and TWR explained+-----------------------------++"ROI" stands for "return on investment". Traditionally this was+computed as a difference between current value of investment and its+initial value, expressed in percentage of the initial value.++ However, this approach is only practical in simple cases, where+investments receives no in-flows or out-flows of money, and where rate+of growth is fixed over time. For more complex scenarios you need+different ways to compute rate of return, and this command implements+two of them: IRR and TWR.++ Internal rate of return, or "IRR" (also called "money-weighted rate+of return") takes into account effects of in-flows and out-flows.+Naively, if you are withdrawing from your investment, your future gains+would be smaller (in absolute numbers), and will be a smaller percentage+of your initial investment, and if you are adding to your investment,+you will receive bigger absolute gains (but probably at the same rate of+return). IRR is a way to compute rate of return for each period between+in-flow or out-flow of money, and then combine them in a way that gives+you a compound annual rate of return that investment is expected to+generate.++ As mentioned before, in-flows and out-flows would be any cash that+you personally put in or withdraw, and for the "roi" command, these are+the postings that match the query in the‘--inv’ argument and NOT match+the query in the‘--pnl’ argument.++ If you manually record changes in the value of your investment as+transactions that balance them against "profit and loss" (or "unrealized+gains") account or use price directives, then in order for IRR to+compute the precise effect of your in-flows and out-flows on the rate of+return, you will need to record the value of your investement on or+close to the days when in- or out-flows occur.++ In technical terms, IRR uses the same approach as computation of net+present value, and tries to find a discount rate that makes net present+value of all the cash flows of your investment to add up to zero. This+could be hard to wrap your head around, especially if you haven’t done+discounted cash flow analysis before. Implementation of IRR in hledger+should produce results that match the ‘XIRR’ formula in Excel.++ Second way to compute rate of return that ‘roi’ command implements is+called "time-weighted rate of return" or "TWR". Like IRR, it will also+break the history of your investment into periods between in-flows,+out-flows and value changes, to compute rate of return per each period+and then a compound rate of return. However, internal workings of TWR+are quite different.++ TWR represents your investment as an imaginary "unit fund" where+in-flows/ out-flows lead to buying or selling "units" of your investment+and changes in its value change the value of "investment unit". Change+in "unit price" over the reporting period gives you rate of return of+your investment.++ References:++ • Explanation of rate of return+ • Explanation of IRR+ • Explanation of TWR+ • Examples of computing IRR and TWR and discussion of the limitations+ of both metrics+++File: hledger.info, Node: stats, Next: tags, Prev: roi, Up: PART 4 COMMANDS++24.27 stats+===========++Show journal and performance statistics.++ The stats command displays summary information for the whole journal,+or a matched part of it. With a reporting interval, it shows a report+for each report period.++ At the end, it shows (in the terminal) the overall run time and+number of transactions processed per second. Note these are approximate+and will vary based on machine, current load, data size, hledger+version, haskell lib versions, GHC version.. but they may be of+interest. The ‘stats’ command’s run time is similar to that of a+single-column balance report.++ Example:++$ hledger stats -f examples/1000x1000x10.journal+Main file : /Users/simon/src/hledger/examples/1000x1000x10.journal+Included files : +Transactions span : 2000-01-01 to 2002-09-27 (1000 days)+Last transaction : 2002-09-26 (6995 days ago)+Transactions : 1000 (1.0 per day)+Transactions last 30 days: 0 (0.0 per day)+Transactions last 7 days : 0 (0.0 per day)+Payees/descriptions : 1000+Accounts : 1000 (depth 10)+Commodities : 26 (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z)+Market prices : 1000 (A)++Run time : 0.12 s+Throughput : 8342 txns/s++ This command supports the -o/–output-file option (but not+-O/–output-format selection).+++File: hledger.info, Node: tags, Next: test, Prev: stats, Up: PART 4 COMMANDS++24.28 tags+==========++List the tags used in the journal, or their values.++ This command lists the tag names used in the journal, whether on+transactions, postings, or account declarations.++ With a TAGREGEX argument, only tag names matching this regular+expression (case insensitive, infix matched) are shown.++ With QUERY arguments, only transactions and accounts matching this+query are considered. If the query involves transaction fields (date:,+desc:, amt:, ...), the search is restricted to the matched transactions+and their accounts.++ With the –values flag, the tags’ unique non-empty values are listed+instead. With -E/–empty, blank/empty values are also shown.++ With –parsed, tags or values are shown in the order they were parsed,+with duplicates included. (Except, tags from account declarations are+always shown first.)++ Tip: remember, accounts also acquire tags from their parents,+postings also acquire tags from their account and transaction,+transactions also acquire tags from their postings.+++File: hledger.info, Node: test, Prev: tags, Up: PART 4 COMMANDS++24.29 test+==========++Run built-in unit tests.++ This command runs the unit tests built in to hledger and hledger-lib,+printing the results on stdout. If any test fails, the exit code will+be non-zero.++ This is mainly used by hledger developers, but you can also use it to+sanity-check the installed hledger executable on your platform. All+tests are expected to pass - if you ever see a failure, please report as+a bug!++ This command also accepts tasty test runner options, written after a+– (double hyphen). Eg to run only the tests in Hledger.Data.Amount,+with ANSI colour codes disabled:++$ hledger test -- -pData.Amount --color=never++ For help on these, see https://github.com/feuerbach/tasty#options+(‘-- --help’ currently doesn’t show them).+++File: hledger.info, Node: PART 5 COMMON TASKS, Prev: PART 4 COMMANDS, Up: Top++25 PART 5: COMMON TASKS+***********************++Here are some quick examples of how to do some basic tasks with hledger.++* Menu:++* Getting help::+* Constructing command lines::+* Starting a journal file::+* Setting opening balances::+* Recording transactions::+* Reconciling::+* Reporting::+* Migrating to a new file::+++File: hledger.info, Node: Getting help, Next: Constructing command lines, Up: PART 5 COMMON TASKS++25.1 Getting help+=================++Here’s how to list commands and view options and command docs:++$ hledger # show available commands+$ hledger --help # show common options+$ hledger CMD --help # show CMD's options, common options and CMD's documentation++ You can also view your hledger version’s manual in several formats by+using the help command. Eg:++$ hledger help # show the hledger manual with info, man or $PAGER (best available)+$ hledger help journal # show the journal topic in the hledger manual+$ hledger help --help # find out more about the help command++ To view manuals and introductory docs on the web, visit+https://hledger.org. Chat and mail list support and discussion archives+can be found at https://hledger.org/support.+++File: hledger.info, Node: Constructing command lines, Next: Starting a journal file, Prev: Getting help, Up: PART 5 COMMON TASKS++25.2 Constructing command lines+===============================++hledger has a flexible command line interface. We strive to keep it+simple and ergonomic, but if you run into one of the sharp edges+described in OPTIONS, here are some tips that might help:++ • command-specific options must go after the command (it’s fine to+ put common options there too: ‘hledger CMD OPTS ARGS’)+ • running add-on executables directly simplifies command line parsing+ (‘hledger-ui OPTS ARGS’)+ • enclose "problematic" args in single quotes+ • if needed, also add a backslash to hide regular expression+ metacharacters from the shell+ • to see how a misbehaving command line is being parsed, add+ ‘--debug=2’.+++File: hledger.info, Node: Starting a journal file, Next: Setting opening balances, Prev: Constructing command lines, Up: PART 5 COMMON TASKS++25.3 Starting a journal file+============================++hledger looks for your accounting data in a journal file,+‘$HOME/.hledger.journal’ by default:++$ hledger stats+The hledger journal file "/Users/simon/.hledger.journal" was not found.+Please create it first, eg with "hledger add" or a text editor.+Or, specify an existing journal file with -f or LEDGER_FILE.++ You can override this by setting the ‘LEDGER_FILE’ environment+variable. It’s a good practice to keep this important file under+version control, and to start a new file each year. So you could do+something like this:++$ mkdir ~/finance+$ cd ~/finance+$ git init+Initialized empty Git repository in /Users/simon/finance/.git/+$ touch 2020.journal+$ echo "export LEDGER_FILE=$HOME/finance/2020.journal" >> ~/.bashrc+$ source ~/.bashrc+$ hledger stats+Main file : /Users/simon/finance/2020.journal+Included files : +Transactions span : to (0 days)+Last transaction : none+Transactions : 0 (0.0 per day)+Transactions last 30 days: 0 (0.0 per day)+Transactions last 7 days : 0 (0.0 per day)+Payees/descriptions : 0+Accounts : 0 (depth 0)+Commodities : 0 ()+Market prices : 0 ()+++File: hledger.info, Node: Setting opening balances, Next: Recording transactions, Prev: Starting a journal file, Up: PART 5 COMMON TASKS++25.4 Setting opening balances+=============================++Pick a starting date for which you can look up the balances of some+real-world assets (bank accounts, wallet..) and liabilities (credit+cards..).++ To avoid a lot of data entry, you may want to start with just one or+two accounts, like your checking account or cash wallet; and pick a+recent starting date, like today or the start of the week. You can+always come back later and add more accounts and older transactions, eg+going back to january 1st.++ Add an opening balances transaction to the journal, declaring the+balances on this date. Here are two ways to do it:++ • The first way: open the journal in any text editor and save an+ entry like this:++ 2020-01-01 * opening balances+ assets:bank:checking $1000 = $1000+ assets:bank:savings $2000 = $2000+ assets:cash $100 = $100+ liabilities:creditcard $-50 = $-50+ equity:opening/closing balances++ These are start-of-day balances, ie whatever was in the account at+ the end of the previous day.++ The * after the date is an optional status flag. Here it means+ "cleared & confirmed".++ The currency symbols are optional, but usually a good idea as+ you’ll be dealing with multiple currencies sooner or later.++ The = amounts are optional balance assertions, providing extra+ error checking.++ • The second way: run ‘hledger add’ and follow the prompts to record+ a similar transaction:++ $ hledger add+ Adding transactions to journal file /Users/simon/finance/2020.journal+ Any command line arguments will be used as defaults.+ Use tab key to complete, readline keys to edit, enter to accept defaults.+ An optional (CODE) may follow transaction dates.+ An optional ; COMMENT may follow descriptions or amounts.+ If you make a mistake, enter < at any prompt to go one step backward.+ To end a transaction, enter . when prompted.+ To quit, enter . at a date prompt or press control-d or control-c.+ Date [2020-02-07]: 2020-01-01+ Description: * opening balances+ Account 1: assets:bank:checking+ Amount 1: $1000+ Account 2: assets:bank:savings+ Amount 2 [$-1000]: $2000+ Account 3: assets:cash+ Amount 3 [$-3000]: $100+ Account 4: liabilities:creditcard+ Amount 4 [$-3100]: $-50+ Account 5: equity:opening/closing balances+ Amount 5 [$-3050]: + Account 6 (or . or enter to finish this transaction): .+ 2020-01-01 * opening balances+ assets:bank:checking $1000+ assets:bank:savings $2000+ assets:cash $100+ liabilities:creditcard $-50+ equity:opening/closing balances $-3050+ + Save this transaction to the journal ? [y]: + Saved.+ Starting the next transaction (. or ctrl-D/ctrl-C to quit)+ Date [2020-01-01]: .++ If you’re using version control, this could be a good time to commit+the journal. Eg:++$ git commit -m 'initial balances' 2020.journal+++File: hledger.info, Node: Recording transactions, Next: Reconciling, Prev: Setting opening balances, Up: PART 5 COMMON TASKS++25.5 Recording transactions+===========================++As you spend or receive money, you can record these transactions using+one of the methods above (text editor, hledger add) or by using the+hledger-iadd or hledger-web add-ons, or by using the import command to+convert CSV data downloaded from your bank.++ Here are some simple transactions, see the hledger_journal(5) manual+and hledger.org for more ideas:++2020/1/10 * gift received+ assets:cash $20+ income:gifts++2020.1.12 * farmers market+ expenses:food $13+ assets:cash++2020-01-15 paycheck+ income:salary+ assets:bank:checking $1000+++File: hledger.info, Node: Reconciling, Next: Reporting, Prev: Recording transactions, Up: PART 5 COMMON TASKS++25.6 Reconciling+================++Periodically you should reconcile - compare your hledger-reported+balances against external sources of truth, like bank statements or your+bank’s website - to be sure that your ledger accurately represents the+real-world balances (and, that the real-world institutions have not made+a mistake!). This gets easy and fast with (1) practice and (2)+frequency. If you do it daily, it can take 2-10 minutes. If you let it+pile up, expect it to take longer as you hunt down errors and+discrepancies.++ A typical workflow:++ 1. Reconcile cash. Count what’s in your wallet. Compare with what+ hledger reports (‘hledger bal cash’). If they are different, try+ to remember the missing transaction, or look for the error in the+ already-recorded transactions. A register report can be helpful+ (‘hledger reg cash’). If you can’t find the error, add an+ adjustment transaction. Eg if you have $105 after the above, and+ can’t explain the missing $2, it could be:++ 2020-01-16 * adjust cash+ assets:cash $-2 = $105+ expenses:misc++ 2. Reconcile checking. Log in to your bank’s website. Compare+ today’s (cleared) balance with hledger’s cleared balance (‘hledger+ bal checking -C’). If they are different, track down the error or+ record the missing transaction(s) or add an adjustment transaction,+ similar to the above. Unlike the cash case, you can usually+ compare the transaction history and running balance from your bank+ with the one reported by ‘hledger reg checking -C’. This will be+ easier if you generally record transaction dates quite similar to+ your bank’s clearing dates.++ 3. Repeat for other asset/liability accounts.++ Tip: instead of the register command, use hledger-ui to see a+live-updating register while you edit the journal: ‘hledger-ui --watch+--register checking -C’++ After reconciling, it could be a good time to mark the reconciled+transactions’ status as "cleared and confirmed", if you want to track+that, by adding the ‘*’ marker. Eg in the paycheck transaction above,+insert ‘*’ between ‘2020-01-15’ and ‘paycheck’++ If you’re using version control, this can be another good time to+commit:++$ git commit -m 'txns' 2020.journal+++File: hledger.info, Node: Reporting, Next: Migrating to a new file, Prev: Reconciling, Up: PART 5 COMMON TASKS++25.7 Reporting+==============++Here are some basic reports.++ Show all transactions:++$ hledger print+2020-01-01 * opening balances+ assets:bank:checking $1000+ assets:bank:savings $2000+ assets:cash $100+ liabilities:creditcard $-50+ equity:opening/closing balances $-3050++2020-01-10 * gift received+ assets:cash $20+ income:gifts++2020-01-12 * farmers market+ expenses:food $13+ assets:cash++2020-01-15 * paycheck+ income:salary+ assets:bank:checking $1000++2020-01-16 * adjust cash+ assets:cash $-2 = $105+ expenses:misc++ Show account names, and their hierarchy:++$ hledger accounts --tree+assets+ bank+ checking+ savings+ cash+equity+ opening/closing balances+expenses+ food+ misc+income+ gifts+ salary+liabilities+ creditcard++ Show all account totals:++$ hledger balance+ $4105 assets+ $4000 bank+ $2000 checking+ $2000 savings+ $105 cash+ $-3050 equity:opening/closing balances+ $15 expenses+ $13 food+ $2 misc+ $-1020 income+ $-20 gifts+ $-1000 salary+ $-50 liabilities:creditcard+--------------------+ 0++ Show only asset and liability balances, as a flat list, limited to+depth 2:++$ hledger bal assets liabilities -2+ $4000 assets:bank+ $105 assets:cash+ $-50 liabilities:creditcard+--------------------+ $4055++ Show the same thing without negative numbers, formatted as a simple+balance sheet:++$ hledger bs -2+Balance Sheet 2020-01-16++ || 2020-01-16 +========================++============+ Assets || +------------------------++------------+ assets:bank || $4000 + assets:cash || $105 +------------------------++------------+ || $4105 +========================++============+ Liabilities || +------------------------++------------+ liabilities:creditcard || $50 +------------------------++------------+ || $50 +========================++============+ Net: || $4055 ++ The final total is your "net worth" on the end date. (Or use ‘bse’+for a full balance sheet with equity.)++ Show income and expense totals, formatted as an income statement:++hledger is +Income Statement 2020-01-01-2020-01-16++ || 2020-01-01-2020-01-16 +===============++=======================+ Revenues || +---------------++-----------------------+ income:gifts || $20 + income:salary || $1000 +---------------++-----------------------+ || $1020 +===============++=======================+ Expenses || +---------------++-----------------------+ expenses:food || $13 + expenses:misc || $2 +---------------++-----------------------+ || $15 +===============++=======================+ Net: || $1005 ++ The final total is your net income during this period.++ Show transactions affecting your wallet, with running total:++$ hledger register cash+2020-01-01 opening balances assets:cash $100 $100+2020-01-10 gift received assets:cash $20 $120+2020-01-12 farmers market assets:cash $-13 $107+2020-01-16 adjust cash assets:cash $-2 $105++ Show weekly posting counts as a bar chart:++$ hledger activity -W+2019-12-30 *****+2020-01-06 ****+2020-01-13 ****+++File: hledger.info, Node: Migrating to a new file, Prev: Reporting, Up: PART 5 COMMON TASKS++25.8 Migrating to a new file+============================++At the end of the year, you may want to continue your journal in a new+file, so that old transactions don’t slow down or clutter your reports,+and to help ensure the integrity of your accounting history. See the+close command.++ If using version control, don’t forget to ‘git add’ the new file.+++Tag Table:+Node: Top210+Node: PART 1 USER INTERFACE3946+Ref: #part-1-user-interface4087+Node: Options4087+Ref: #options4206+Node: General options4348+Ref: #general-options4473+Node: Command options8923+Ref: #command-options9074+Node: Command arguments9490+Ref: #command-arguments9648+Node: Special characters10550+Ref: #special-characters10713+Node: Single escaping shell metacharacters10876+Ref: #single-escaping-shell-metacharacters11117+Node: Double escaping regular expression metacharacters11752+Ref: #double-escaping-regular-expression-metacharacters12063+Node: Triple escaping for add-on commands12633+Ref: #triple-escaping-for-add-on-commands12893+Node: Less escaping13561+Ref: #less-escaping13715+Node: Unicode characters14053+Ref: #unicode-characters14218+Node: Regular expressions15650+Ref: #regular-expressions15790+Node: Environment17644+Ref: #environment17755+Node: Input19366+Ref: #input19466+Node: Data formats20029+Ref: #data-formats20142+Node: Multiple files21594+Ref: #multiple-files21731+Node: Strict mode22216+Ref: #strict-mode22326+Node: Commands23080+Ref: #commands23181+Node: Add-on commands23665+Ref: #add-on-commands23767+Node: Output24934+Ref: #output25037+Node: Output destination25153+Ref: #output-destination25284+Node: Output format25713+Ref: #output-format25859+Node: CSV output27431+Ref: #csv-output27547+Node: HTML output27652+Ref: #html-output27790+Node: JSON output27890+Ref: #json-output28028+Node: SQL output28960+Ref: #sql-output29076+Node: Commodity styles29599+Ref: #commodity-styles29739+Node: Colour30346+Ref: #colour30464+Node: Box-drawing30898+Ref: #box-drawing31022+Node: Debug output31336+Ref: #debug-output31447+Node: Limitations32122+Ref: #limitations32242+Node: Troubleshooting33017+Ref: #troubleshooting33158+Node: PART 2 DATA FORMATS35680+Ref: #part-2-data-formats35827+Node: Journal35827+Ref: #journal35938+Node: Journal cheatsheet36581+Ref: #journal-cheatsheet36722+Node: About journal format40710+Ref: #about-journal-format40872+Node: Comments42410+Ref: #comments42542+Node: Transactions43396+Ref: #transactions43521+Node: Dates44555+Ref: #dates44664+Node: Simple dates44709+Ref: #simple-dates44827+Node: Posting dates45359+Ref: #posting-dates45479+Node: Status46462+Ref: #status46565+Node: Code48317+Ref: #code48422+Node: Description48654+Ref: #description48787+Node: Payee and note49109+Ref: #payee-and-note49217+Node: Transaction comments49564+Ref: #transaction-comments49719+Node: Postings50090+Ref: #postings50225+Node: Account names51234+Ref: #account-names51366+Node: Amounts53068+Ref: #amounts53185+Node: Decimal marks digit group marks54174+Ref: #decimal-marks-digit-group-marks54351+Node: Commodity55375+Ref: #commodity55564+Node: Directives influencing number parsing and display56546+Ref: #directives-influencing-number-parsing-and-display56807+Node: Commodity display style57269+Ref: #commodity-display-style57477+Node: Rounding59688+Ref: #rounding59808+Node: Costs60109+Ref: #costs60227+Node: Other cost/lot notations62258+Ref: #other-costlot-notations62392+Node: Balance assertions65145+Ref: #balance-assertions65298+Node: Assertions and ordering66391+Ref: #assertions-and-ordering66582+Node: Assertions and multiple included files67284+Ref: #assertions-and-multiple-included-files67546+Node: Assertions and multiple -f files68054+Ref: #assertions-and-multiple--f-files68307+Node: Assertions and commodities68716+Ref: #assertions-and-commodities68940+Node: Assertions and prices70130+Ref: #assertions-and-prices70338+Node: Assertions and subaccounts70769+Ref: #assertions-and-subaccounts70992+Node: Assertions and virtual postings71334+Ref: #assertions-and-virtual-postings71574+Node: Assertions and auto postings71714+Ref: #assertions-and-auto-postings71946+Node: Assertions and precision72617+Ref: #assertions-and-precision72801+Node: Posting comments73068+Ref: #posting-comments73216+Node: Tags73601+Ref: #tags73717+Node: Tag values74922+Ref: #tag-values75013+Node: Directives75786+Ref: #directives75915+Node: Directive effects77783+Ref: #directive-effects77939+Node: Directives and multiple files81022+Ref: #directives-and-multiple-files81202+Node: account directive81912+Ref: #account-directive82074+Node: Account comments83494+Ref: #account-comments83646+Node: Account subdirectives84166+Ref: #account-subdirectives84359+Node: Account error checking84501+Ref: #account-error-checking84701+Node: Account display order85920+Ref: #account-display-order86110+Node: Account types87249+Ref: #account-types87392+Node: alias directive91127+Ref: #alias-directive91294+Node: Basic aliases92354+Ref: #basic-aliases92487+Node: Regex aliases93241+Ref: #regex-aliases93400+Node: Combining aliases94294+Ref: #combining-aliases94474+Node: Aliases and multiple files95768+Ref: #aliases-and-multiple-files95974+Node: end aliases directive96559+Ref: #end-aliases-directive96784+Node: Aliases can generate bad account names96933+Ref: #aliases-can-generate-bad-account-names97183+Node: Aliases and account types97780+Ref: #aliases-and-account-types97974+Node: commodity directive98676+Ref: #commodity-directive98856+Node: Commodity error checking101460+Ref: #commodity-error-checking101608+Node: decimal-mark directive102137+Ref: #decimal-mark-directive102325+Node: include directive102726+Ref: #include-directive102896+Node: P directive103844+Ref: #p-directive103995+Node: payee directive104894+Ref: #payee-directive105049+Node: tag directive105369+Ref: #tag-directive105530+Node: Periodic transactions106002+Ref: #periodic-transactions106168+Node: Periodic rule syntax107906+Ref: #periodic-rule-syntax108086+Node: Periodic rules and relative dates108741+Ref: #periodic-rules-and-relative-dates109009+Node: Two spaces between period expression and description!109548+Ref: #two-spaces-between-period-expression-and-description109827+Node: Other syntax110517+Ref: #other-syntax110643+Node: Auto postings111288+Ref: #auto-postings111424+Node: Auto postings and multiple files113935+Ref: #auto-postings-and-multiple-files114137+Node: Auto postings and dates114354+Ref: #auto-postings-and-dates114626+Node: Auto postings and transaction balancing / inferred amounts / balance assertions114801+Ref: #auto-postings-and-transaction-balancing-inferred-amounts-balance-assertions115140+Node: Auto posting tags115647+Ref: #auto-posting-tags115860+Node: Balance assignments116522+Ref: #balance-assignments116702+Node: Balance assignments and prices118036+Ref: #balance-assignments-and-prices118206+Node: Bracketed posting dates118417+Ref: #bracketed-posting-dates118603+Node: D directive119147+Ref: #d-directive119321+Node: apply account directive120989+Ref: #apply-account-directive121175+Node: Y directive121874+Ref: #y-directive122040+Node: Secondary dates122884+Ref: #secondary-dates123040+Node: Star comments123872+Ref: #star-comments124034+Node: Valuation expressions124574+Ref: #valuation-expressions124753+Node: Virtual postings124875+Ref: #virtual-postings125056+Node: Other Ledger directives126628+Ref: #other-ledger-directives126793+Node: CSV127363+Ref: #csv127456+Node: CSV rules cheatsheet129559+Ref: #csv-rules-cheatsheet129691+Node: separator131459+Ref: #separator131590+Node: skip132168+Ref: #skip132280+Node: date-format132863+Ref: #date-format132988+Node: timezone133734+Ref: #timezone133861+Node: newest-first134894+Ref: #newest-first135036+Node: intra-day-reversed135620+Ref: #intra-day-reversed135778+Node: decimal-mark136275+Ref: #decimal-mark136420+Node: fields list136759+Ref: #fields-list136900+Node: Field assignment138623+Ref: #field-assignment138767+Node: Field names139816+Ref: #field-names139947+Node: date field141168+Ref: #date-field141286+Node: date2 field141338+Ref: #date2-field141479+Node: status field141541+Ref: #status-field141684+Node: code field141739+Ref: #code-field141884+Node: description field141935+Ref: #description-field142095+Node: comment field142160+Ref: #comment-field142315+Node: account field142628+Ref: #account-field142778+Node: amount field143374+Ref: #amount-field143523+Node: currency field145628+Ref: #currency-field145781+Node: balance field146050+Ref: #balance-field146182+Node: if block146570+Ref: #if-block146695+Node: Matchers148119+Ref: #matchers148233+Node: if table149763+Ref: #if-table149889+Node: balance-type151325+Ref: #balance-type151458+Node: include152166+Ref: #include152297+Node: Working with CSV152747+Ref: #working-with-csv152894+Node: Rapid feedback153265+Ref: #rapid-feedback153398+Node: Valid CSV153854+Ref: #valid-csv154000+Node: File Extension154754+Ref: #file-extension154927+Node: Reading CSV from standard input155517+Ref: #reading-csv-from-standard-input155741+Node: Reading multiple CSV files155907+Ref: #reading-multiple-csv-files156125+Node: Valid transactions156374+Ref: #valid-transactions156568+Node: Deduplicating importing157196+Ref: #deduplicating-importing157391+Node: Setting amounts158437+Ref: #setting-amounts158608+Node: Amount signs161131+Ref: #amount-signs161299+Node: Setting currency/commodity162038+Ref: #setting-currencycommodity162242+Node: Amount decimal places163434+Ref: #amount-decimal-places163640+Node: Referencing other fields163958+Ref: #referencing-other-fields164171+Node: How CSV rules are evaluated165074+Ref: #how-csv-rules-are-evaluated165291+Node: Well factored rules166804+Ref: #well-factored-rules166972+Node: CSV rules examples167310+Ref: #csv-rules-examples167445+Node: Bank of Ireland167510+Ref: #bank-of-ireland167647+Node: Coinbase169115+Ref: #coinbase169253+Node: Amazon170306+Ref: #amazon170431+Node: Paypal172156+Ref: #paypal172264+Node: Timeclock179910+Ref: #timeclock180015+Node: Timedot182183+Ref: #timedot182306+Node: PART 3 REPORTING CONCEPTS187157+Ref: #part-3-reporting-concepts187321+Node: Time periods187321+Ref: #time-periods187455+Node: Report start & end date187573+Ref: #report-start-end-date187725+Node: Smart dates189458+Ref: #smart-dates189611+Node: Report intervals191571+Ref: #report-intervals191726+Node: Date adjustment192178+Ref: #date-adjustment192338+Node: Period expressions193670+Ref: #period-expressions193811+Node: Period expressions with a report interval195647+Ref: #period-expressions-with-a-report-interval195881+Node: More complex report intervals196111+Ref: #more-complex-report-intervals196356+Node: Multiple weekday intervals198285+Ref: #multiple-weekday-intervals198474+Node: Depth199338+Ref: #depth199440+Node: Queries199760+Ref: #queries199862+Node: Query types200807+Ref: #query-types200928+Node: Combining query terms204268+Ref: #combining-query-terms204445+Node: Queries and command options205543+Ref: #queries-and-command-options205742+Node: Queries and valuation206007+Ref: #queries-and-valuation206202+Node: Querying with account aliases206441+Ref: #querying-with-account-aliases206652+Node: Querying with cost or value206794+Ref: #querying-with-cost-or-value206971+Node: Pivoting207280+Ref: #pivoting207394+Node: Generating data208882+Ref: #generating-data209014+Node: Forecasting209512+Ref: #forecasting209637+Node: Budgeting212524+Ref: #budgeting212644+Node: Cost reporting212915+Ref: #cost-reporting213043+Node: -B Convert to cost214158+Ref: #b-convert-to-cost214314+Node: Equity conversion postings215722+Ref: #equity-conversion-postings215936+Node: Inferring equity postings from cost216831+Ref: #inferring-equity-postings-from-cost217080+Node: Inferring cost from equity postings217899+Ref: #inferring-cost-from-equity-postings218147+Node: When to infer cost/equity219956+Ref: #when-to-infer-costequity220174+Node: How to record conversions220582+Ref: #how-to-record-conversions220774+Node: Conversion with implicit cost221065+Ref: #conversion-with-implicit-cost221270+Node: Conversion with explicit cost222175+Ref: #conversion-with-explicit-cost222420+Node: Conversion with equity postings222847+Ref: #conversion-with-equity-postings223116+Node: Conversion with equity postings and explicit cost223953+Ref: #conversion-with-equity-postings-and-explicit-cost224220+Node: Cost tips224694+Ref: #cost-tips224820+Node: Valuation225556+Ref: #valuation225680+Node: -V Value226466+Ref: #v-value226592+Node: -X Value in specified commodity226791+Ref: #x-value-in-specified-commodity226986+Node: Valuation date227143+Ref: #valuation-date227314+Node: Finding market price227753+Ref: #finding-market-price227958+Node: --infer-market-prices market prices from transactions229138+Ref: #infer-market-prices-market-prices-from-transactions229416+Node: Valuation commodity232262+Ref: #valuation-commodity232475+Node: Simple valuation examples233720+Ref: #simple-valuation-examples233918+Node: --value Flexible valuation234581+Ref: #value-flexible-valuation234787+Node: More valuation examples236473+Ref: #more-valuation-examples236682+Node: Interaction of valuation and queries238693+Ref: #interaction-of-valuation-and-queries238934+Node: Effect of valuation on reports239414+Ref: #effect-of-valuation-on-reports239611+Node: PART 4 COMMANDS247370+Ref: #part-4-commands247513+Node: Commands overview247883+Ref: #commands-overview248017+Node: DATA ENTRY248196+Ref: #data-entry248320+Node: DATA CREATION248523+Ref: #data-creation248677+Node: DATA MANAGEMENT248801+Ref: #data-management248966+Node: REPORTS FINANCIAL249091+Ref: #reports-financial249266+Node: REPORTS VERSATILE249581+Ref: #reports-versatile249754+Node: REPORTS BASIC250015+Ref: #reports-basic250167+Node: HELP250700+Ref: #help250822+Node: ADD-ONS250881+Ref: #add-ons250987+Node: accounts251584+Ref: #accounts251717+Node: activity253692+Ref: #activity253811+Node: add254185+Ref: #add254295+Node: aregister257156+Ref: #aregister257277+Node: aregister and custom posting dates260253+Ref: #aregister-and-custom-posting-dates260419+Node: balance260987+Ref: #balance261113+Node: balance features262118+Ref: #balance-features262258+Node: Simple balance report264388+Ref: #simple-balance-report264573+Node: Balance report line format266218+Ref: #balance-report-line-format266420+Node: Filtered balance report268670+Ref: #filtered-balance-report268862+Node: List or tree mode269189+Ref: #list-or-tree-mode269357+Node: Depth limiting270732+Ref: #depth-limiting270898+Node: Dropping top-level accounts271515+Ref: #dropping-top-level-accounts271715+Node: Showing declared accounts272029+Ref: #showing-declared-accounts272228+Node: Sorting by amount272769+Ref: #sorting-by-amount272936+Node: Percentages273626+Ref: #percentages273785+Node: Multi-period balance report274355+Ref: #multi-period-balance-report274555+Node: Balance change end balance276948+Ref: #balance-change-end-balance277157+Node: Balance report types278605+Ref: #balance-report-types278786+Node: Calculation type279302+Ref: #calculation-type279457+Node: Accumulation type279988+Ref: #accumulation-type280168+Node: Valuation type281096+Ref: #valuation-type281284+Node: Combining balance report types282351+Ref: #combining-balance-report-types282545+Node: Budget report284449+Ref: #budget-report284601+Node: Budget report start date290335+Ref: #budget-report-start-date290513+Node: Budgets and subaccounts291875+Ref: #budgets-and-subaccounts292082+Node: Selecting budget goals295568+Ref: #selecting-budget-goals295767+Node: Budget vs forecast296814+Ref: #budget-vs-forecast296973+Node: Data layout298673+Ref: #data-layout298823+Node: Useful balance reports306764+Ref: #useful-balance-reports306914+Node: balancesheet308067+Ref: #balancesheet308212+Node: balancesheetequity309578+Ref: #balancesheetequity309736+Node: cashflow311179+Ref: #cashflow311310+Node: check312796+Ref: #check312910+Node: Basic checks313716+Ref: #basic-checks313836+Node: Strict checks314374+Ref: #strict-checks314517+Node: Other checks314958+Ref: #other-checks315100+Node: Custom checks315677+Ref: #custom-checks315834+Node: More about specific checks316255+Ref: #more-about-specific-checks316417+Node: close317149+Ref: #close317260+Node: close and costs319898+Ref: #close-and-costs320042+Node: close and balance assertions320331+Ref: #close-and-balance-assertions320533+Node: Example retain earnings321704+Ref: #example-retain-earnings321921+Node: Example migrate balances to a new file322279+Ref: #example-migrate-balances-to-a-new-file322544+Node: Example excluding closing/opening transactions323097+Ref: #example-excluding-closingopening-transactions323346+Node: codes324524+Ref: #codes324641+Node: commodities325517+Ref: #commodities325653+Node: descriptions325723+Ref: #descriptions325860+Node: diff326151+Ref: #diff326266+Node: files327312+Ref: #files327421+Node: help327562+Ref: #help-1327671+Node: import328661+Ref: #import328784+Node: Deduplication329892+Ref: #deduplication330017+Node: Import testing331939+Ref: #import-testing332104+Node: Importing balance assignments332955+Ref: #importing-balance-assignments333161+Node: Commodity display styles333818+Ref: #commodity-display-styles333991+Node: incomestatement334120+Ref: #incomestatement334262+Node: notes335629+Ref: #notes335751+Node: payees336113+Ref: #payees336228+Node: prices336753+Ref: #prices336868+Node: print337170+Ref: #print337285+Node: register342731+Ref: #register342853+Node: Custom register output347962+Ref: #custom-register-output348093+Node: rewrite349468+Ref: #rewrite349586+Node: Re-write rules in a file351498+Ref: #re-write-rules-in-a-file351661+Node: Diff output format352814+Ref: #diff-output-format352997+Node: rewrite vs print --auto354109+Ref: #rewrite-vs.-print---auto354271+Node: roi354845+Ref: #roi354952+Node: Spaces and special characters in --inv and --pnl356713+Ref: #spaces-and-special-characters-in---inv-and---pnl356961+Node: Semantics of --inv and --pnl357459+Ref: #semantics-of---inv-and---pnl357706+Node: IRR and TWR explained359584+Ref: #irr-and-twr-explained359744+Node: stats362856+Ref: #stats362964+Node: tags364361+Ref: #tags-1364468+Node: test365485+Ref: #test365578+Node: PART 5 COMMON TASKS366328+Ref: #part-5-common-tasks366461+Node: Getting help366735+Ref: #getting-help366876+Node: Constructing command lines367640+Ref: #constructing-command-lines367841+Node: Starting a journal file368522+Ref: #starting-a-journal-file368729+Node: Setting opening balances369927+Ref: #setting-opening-balances370132+Node: Recording transactions373285+Ref: #recording-transactions373474+Node: Reconciling374030+Ref: #reconciling374182+Node: Reporting376495+Ref: #reporting376644+Node: Migrating to a new file380633+Ref: #migrating-to-a-new-file380790 End Tag Table
hledger.txt view
@@ -18,8 +18,8 @@ and largely compatible with ledger(1), and largely interconvertible with beancount(1). - This manual is for hledger's command line interface, version 1.29. It- also describes the common options, file formats and concepts used by+ This manual is for hledger's command line interface, version 1.29.1.+ It also describes the common options, file formats and concepts used by all hledger programs. It might accidentally teach you some bookkeep- ing/accounting as well! You don't need to know everything in here to use hledger productively, but when you have a question about function-@@ -8659,4 +8659,4 @@ -hledger-1.29 March 2023 HLEDGER(1)+hledger-1.29.1 March 2023 HLEDGER(1)