
hledger_journal(5)           hledger User Manuals           hledger_journal(5)



NAME
       Journal - hledger's default file format, representing a General Journal

DESCRIPTION
       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 get-
       ting.

       You can use hledger without learning any more about this file; just use
       the  add  or web commands to create and update it.  Many users, though,
       also edit the  journal  file  directly  with  a  text  editor,  perhaps
       assisted by the helper modes for emacs or vim.

       Here's an example:

              ; A sample journal file. This is a comment.

              2008/01/01 income               ; <- transaction's first line starts in column 0, contains date and description
                  assets:bank:checking  $1    ; <- posting lines start with whitespace, each contains an account name
                  income:salary        $-1    ;    followed by at least two spaces and an amount

              2008/06/01 gift
                  assets:bank:checking  $1    ; <- at least two postings in a transaction
                  income:gifts         $-1    ; <- their amounts must balance to 0

              2008/06/02 save
                  assets:bank:saving    $1
                  assets:bank:checking        ; <- one amount may be omitted; here $-1 is inferred

              2008/06/03 eat & shop           ; <- description can be anything
                  expenses:food         $1
                  expenses:supplies     $1    ; <- this transaction debits two expense accounts
                  assets:cash                 ; <- $-2 inferred

              2008/10/01 take a loan
                  assets:bank:checking  $1
                  liabilities:debts    $-1

              2008/12/31 * pay off            ; <- an optional * or ! after the date means "cleared" (or anything you want)
                  liabilities:debts     $1
                  assets:bank:checking

FILE FORMAT
   Transactions
       Transactions  are  movements  of  some  quantity of commodities between
       named accounts.  Each transaction is represented  by  a  journal  entry
       beginning  with a simple date in column 0.  This can be followed by any
       of the following, separated by spaces:

       o (optional) a status character (empty, !, or *)

       o (optional) a transaction code (any short number or text, enclosed  in
         parentheses)

       o (optional) a transaction description (any remaining text until end of
         line or a semicolon)

       o (optional) a transaction comment  (any  remaining  text  following  a
         semicolon until end of line)

       Then  comes zero or more (but usually at least 2) indented lines repre-
       senting...

   Postings
       A posting is an addition of some amount to, or removal of  some  amount
       from,  an account.  Each posting line begins with at least one space or
       tab (2 or 4 spaces is common), followed by:

       o (optional) a status character (empty, !, or *), followed by a space

       o (required) an account name (any text,  optionally  containing  single
         spaces, until end of line or a double space)

       o (optional) two or more spaces or tabs followed by an amount.

       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 con-
       venience,  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 spa-
       ces.  But if you accidentally leave only one space (or tab) before  the
       amount, the amount will be considered part of the account name.

   Dates
   Simple dates
       Within  a journal file, transaction dates use Y/M/D (or Y-M-D or Y.M.D)
       Leading zeros are optional.  The year may be omitted, in which case  it
       will  be  inferred  from  the  context  -  the current transaction, the
       default year set with a default year directive,  or  the  current  date
       when  the command is run.  Some examples: 2010/01/31, 1/31, 2010-01-31,
       2010.1.31.

   Secondary dates
       Real-life transactions sometimes involve more than one date  -  eg  the
       date you write a cheque, and the date it clears in your bank.  When you
       want to model this, eg for more  accurate  balances,  you  can  specify
       individual  posting dates, which I recommend.  Or, you can use the sec-
       ondary dates (aka auxiliary/effective  dates)  feature,  supported  for
       compatibility with Ledger.

       A secondary date can be written after the primary date, separated by an
       equals sign.  The primary date, on the left, is used  by  default;  the
       secondary  date,  on the right, is used when the --date2 flag is speci-
       fied (--aux-date or --effective also work).

       The meaning of secondary dates is up to you, but it's best to follow  a
       consistent  rule.   Eg  write  the bank's clearing date as primary, and
       when needed, the date the transaction was initiated as secondary.

       Here's an example.  Note that a secondary date will use the year of the
       primary date if unspecified.

              2010/2/23=2/19 movie ticket
                expenses:cinema                   $10
                assets:checking

              $ hledger register checking
              2010/02/23 movie ticket         assets:checking                $-10         $-10

              $ hledger register checking --date2
              2010/02/19 movie ticket         assets:checking                $-10         $-10

       Secondary  dates require some effort; you must use them consistently in
       your journal entries and remember whether to use or not use the --date2
       flag for your reports.  They are included in hledger for Ledger compat-
       ibility, but posting dates are  a  more  powerful  and  less  confusing
       alternative.

   Posting dates
       You  can  give  individual  postings a different date from their parent
       transaction, by adding a posting comment containing a tag  (see  below)
       like date:DATE.  This is probably the best way to control posting dates
       precisely.  Eg in  this  example  the  expense  should  appear  in  May
       reports,  and the deduction from checking should be reported on 6/1 for
       easy bank reconciliation:

              2015/5/30
                  expenses:food     $10   ; food purchased on saturday 5/30
                  assets:checking         ; bank cleared it on monday, date:6/1

              $ hledger -f t.j register food
              2015/05/30                      expenses:food                  $10           $10

              $ hledger -f t.j register checking
              2015/06/01                      assets:checking               $-10          $-10

       DATE should be a simple date; if the year is not specified it will  use
       the  year  of  the  transaction's date.  You can set the secondary date
       similarly, with date2:DATE2.  The date: or  date2:  tags  must  have  a
       valid  simple  date  value  if they are present, eg a date: tag with no
       value is not allowed.

       Ledger's earlier, more compact bracketed date syntax is also supported:
       [DATE],  [DATE=DATE2]  or  [=DATE2].  hledger will attempt to parse any
       square-bracketed sequence of the 0123456789/-.= characters in this way.
       With  this  syntax, DATE infers its year from the transaction and DATE2
       infers its year from DATE.

   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 pend-
       ing, 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 short-
       cuts for working with status.  Eg in Emacs ledger-mode, you can  toggle
       transaction status with C-c C-e, or posting status with C-c C-c.

       What  "uncleared", "pending", and "cleared" actually mean is up to you.
       Here's one suggestion:


       status       meaning
       --------------------------------------------------------------------------
       uncleared    recorded but not yet reconciled; needs review
       pending      tentatively reconciled (if needed, eg during a big reconcil-
                    iation)
       cleared      complete, reconciled as far as possible, and considered cor-
                    rect

       With this scheme, you would use -PC to see the current balance at  your
       bank,  -U  to  see  things which will probably hit your bank soon (like
       uncashed checks), and no flags to see the most up-to-date state of your
       finances.

   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.

   Payee and note
       You  can  optionally  include  a | (pipe) character in a description to
       subdivide it into a payee/payer name on the left and  additional  notes
       on  the  right.   This may be worthwhile if you need to do more precise
       querying and pivoting by payee.

   Account names
       Account names typically have several parts separated by a  full  colon,
       from  which hledger derives a hierarchical chart of accounts.  They can
       be anything you like, but  in  finance  there  are  traditionally  five
       top-level  accounts: assets, liabilities, income, expenses, and equity.

       Account names may contain single  spaces,  eg:  assets:accounts receiv-
       able.   Because  of  this,  they must always be followed by two or more
       spaces (or newline).

       Account names can be aliased.

   Amounts
       After the account name, there is usually an amount.  Important: between
       account name and amount, there must be two or more spaces.

       Amounts  consist of a number and (usually) a currency symbol or commod-
       ity name.  Some examples:

       2.00001
       $1
       4000 AAPL
       3 "green apples"
       -$1,000,000.00
       INR 9,99,99,999.00
       EUR -2.000.000,00

       As you can see, the amount format is somewhat flexible:

       o amounts are a number (the "quantity") and optionally a currency  sym-
         bol/commodity name (the "commodity").

       o the  commodity  is  a  symbol, word, or phrase, on the left or right,
         with or without a separating space.  If the commodity  contains  num-
         bers,  spaces  or  non-word punctuation it must be enclosed in double
         quotes.

       o negative amounts with a commodity on the left can have the minus sign
         before or after it

       o digit  groups  (thousands, or any other grouping) can be separated by
         commas (in which case period is used for decimal  point)  or  periods
         (in which case comma is used for decimal point)

       You  can  use  any  of  these variations when recording data.  However,
       there is some ambiguous way of representing  numbers  like  $1.000  and
       $1,000  both  may  mean  either one thousand or one dollar.  By default
       hledger will assume that this is sole delimiter is used only for  deci-
       mals.   On  the other hand commodity format declared prior to that line
       will help to resolve that ambiguity differently:

              commodity $1,000.00

              2017/12/25 New life of Scrooge
                  expenses:gifts  $1,000
                  assets

       Though journal may contain  mixed  styles  to  represent  amount,  when
       hledger  displays  amounts, it will choose a consistent format for each
       commodity.  (Except for price amounts, which are  always  formatted  as
       written).  The display format is chosen as follows:

       o if there is a commodity directive specifying the format, that is used

       o otherwise the format is inferred from the  first  posting  amount  in
         that  commodity  in the journal, and the precision (number of decimal
         places) will be the maximum from all posting amounts in that commmod-
         ity

       o or  if  there are no such amounts in the journal, a default format is
         used (like $1000.00).

       Price amounts and amounts in D directives usually don't  affect  amount
       format  inference,  but  in  some situations they can do so indirectly.
       (Eg when D's default commodity is applied to a  commodity-less  amount,
       or when an amountless posting is balanced using a price's commodity, or
       when -V is used.) If you find this causing problems,  set  the  desired
       format with a commodity directive.

   Virtual Postings
       When  you  parenthesise  the  account name in a posting, we call that a
       virtual posting, which means:

       o it is ignored when checking that the transaction is balanced

       o it is excluded from reports when the --real/-R flag is used,  or  the
         real:1 query.

       You  could  use  this,  eg, to set an account's opening balance without
       needing to use the equity:opening balances account:

              1/1 special unbalanced posting to set initial balance
                (assets:checking)   $1000

       When the account name is bracketed, we call it a balanced virtual post-
       ing.  This is like an ordinary virtual posting except the balanced vir-
       tual postings in a transaction must balance to 0, like the  real  post-
       ings  (but  separately  from them).  Balanced virtual postings are also
       excluded by --real/-R or real:1.

              1/1 buy food with cash, and update some budget-tracking subaccounts elsewhere
                expenses:food                   $10
                assets:cash                    $-10
                [assets:checking:available]     $10
                [assets:checking:budget:food]  $-10

       Virtual postings have some legitimate uses, but those are few.  You can
       usually  find an equivalent journal entry using real postings, which is
       more correct and provides better error checking.

   Balance Assertions
       hledger supports Ledger-style  balance  assertions  in  journal  files.
       These  look  like =EXPECTEDBALANCE following a posting's amount.  Eg in
       this example we assert the expected dollar balance in accounts a and  b
       after each posting:

              2013/1/1
                a   $1  =$1
                b       =$-1

              2013/1/2
                a   $1  =$2
                b  $-1  =$-2

       After reading a journal file, hledger will check all balance assertions
       and report an error if any of them fail.  Balance assertions  can  pro-
       tect  you  from, eg, inadvertently disrupting reconciled balances while
       cleaning up old entries.  You can disable  them  temporarily  with  the
       --ignore-assertions  flag,  which  can be useful for troubleshooting or
       for reading Ledger files.

   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 dif-
       ferent from Ledger, which sorts assertions only by parse order.  (Also,
       Ledger  assertions  do not see the accumulated effect of repeated post-
       ings to the same account within a transaction.)

       So, hledger balance assertions keep  working  if  you  reorder  differ-
       ently-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 con-
       trol over the order of postings and assertions within a day, so you can
       assert intra-day balances.

   Assertions and included files
       With  included  files, things are a little more complicated.  Including
       preserves the ordering of postings and assertions.  If you have  multi-
       ple  postings  to  an  account  on the same day, split across different
       files, and you also want to assert the account's balance  on  the  same
       day, you'll have to put the assertion in the right file.

   Assertions and multiple -f options
       Balance assertions don't work well across files specified with multiple
       -f options.  Use include or concatenate the files instead.

   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.  We could call this a  par-
       tial  balance  assertion.  This is compatible with Ledger, and makes it
       possible to make assertions about accounts containing multiple commodi-
       ties.

       To  assert  each commodity's balance in such a multi-commodity account,
       you can add multiple postings (with amount 0 if necessary).   But  note
       that  no  matter  how  many  assertions  you add, you can't be sure the
       account does not contain some unexpected commodity.  (We'll add support
       for this kind of total balance assertion if there's demand.)

   Assertions and subaccounts
       Balance  assertions  do  not  count  the balance from subaccounts; they
       check the posted account's exclusive balance.  For example:

              1/1
                checking:fund   1 = 1  ; post to this subaccount, its balance is now 1
                checking        1 = 1  ; post to the parent account, its exclusive balance is now 1
                equity

       The balance report's flat mode  shows  these  exclusive  balances  more
       clearly:

              $ hledger bal checking --flat
                                 1  checking
                                 1  checking:fund
              --------------------
                                 2

   Assertions and virtual postings
       Balance assertions are checked against all postings, both real and vir-
       tual.  They are not affected by the --real/-R flag or real: query.

   Balance Assignments
       Ledger-style balance assignments are also supported.   These  are  like
       balance  assertions, but with no posting amount on the left side of the
       equals sign; instead it is calculated automatically so  as  to  satisfy
       the  assertion.   This  can be a convenience during data entry, eg when
       setting opening balances:

              ; starting a new journal, set asset account balances
              2016/1/1 opening balances
                assets:checking            = $409.32
                assets:savings             = $735.24
                assets:cash                 = $42
                equity:opening balances

       or when adjusting a balance to reality:

              ; no cash left; update balance, record any untracked spending as a generic expense
              2016/1/15
                assets:cash    = $0
                expenses:misc

       The calculated amount depends on the account's balance in the commodity
       at  that  point  (which depends on the previously-dated postings of the
       commodity to that account since the last balance assertion  or  assign-
       ment).  Note that using balance assignments makes your journal a little
       less explicit; to know the exact amount posted, you have to run hledger
       or do the calculations yourself, instead of just reading it.

   Prices
   Transaction prices
       Within a transaction, you can note an amount's price in another commod-
       ity.  This can be used to document the cost (in a purchase) or  selling
       price  (in  a  sale).   For  example,  transaction prices are useful to
       record purchases of a foreign currency.

       Transaction prices are fixed, and do not  change  over  time.   (Ledger
       users:  Ledger  uses a different syntax for fixed prices, {=UNITPRICE},
       which hledger currently ignores).

       There are several ways to record a transaction price:

       1. Write the price per unit, as @ UNITPRICE after the amount:

                  2009/1/1
                    assets:euros     100 @ $1.35  ; one hundred euros purchased at $1.35 each
                    assets:dollars                 ; balancing amount is -$135.00

       2. Write the total price, as @@ TOTALPRICE after the amount:

                  2009/1/1
                    assets:euros     100 @@ $135  ; one hundred euros purchased at $135 for the lot
                    assets:dollars

       3. Specify amounts for all postings, using exactly two commodities, and
          let hledger infer the price that balances the transaction:

                  2009/1/1
                    assets:euros     100          ; one hundred euros purchased
                    assets:dollars  $-135          ; for $135

       Amounts  with  transaction  prices  can be displayed in the transaction
       price's commodity by using the -B/--cost flag (except for #551) ("B" is
       from  "cost Basis").  Eg for the above, here is how -B affects the bal-
       ance report:

              $ hledger bal -N --flat
                             $-135  assets:dollars
                              100  assets:euros
              $ hledger bal -N --flat -B
                             $-135  assets:dollars
                              $135  assets:euros    # <- the euros' cost

       Note -B is sensitive to the order of postings when a transaction  price
       is  inferred:  the  inferred price will be in the commodity of the last
       amount.  So if example 3's postings are reversed, while the transaction
       is equivalent, -B shows something different:

              2009/1/1
                assets:dollars  $-135               ; 135 dollars sold
                assets:euros     100               ; for 100 euros

              $ hledger bal -N --flat -B
                             -100  assets:dollars  # <- the dollars' selling price
                              100  assets:euros

   Market prices
       Market  prices are not tied to a particular transaction; they represent
       historical exchange rates between two commodities.  (Ledger calls  them
       historical  prices.)  For  example,  the  prices  published  by a stock
       exchange or the foreign exchange market.  hledger can use these  prices
       to show the market value of things at a given date, see market value.

       To  record market prices, use P directives in the main journal or in an
       included file.  Their format is:

              P DATE COMMODITYBEINGPRICED UNITPRICE

       DATE is a simple date as usual.  COMMODITYBEINGPRICED is the symbol  of
       the  commodity  being  priced.  UNITPRICE is an ordinary amount (symbol
       and quantity) in a second commodity, specifying the unit price or  con-
       version  rate  for  the  first commodity in terms of the second, on the
       given date.

       For example, the following directives say that one euro was worth  1.35
       US dollars during 2009, and $1.40 from 2010 onward:

              P 2009/1/1  $1.35
              P 2010/1/1  $1.40

   Comments
       Lines in the journal beginning with a semicolon (;) or hash (#) or star
       (*) are comments, and will be ignored.  (Star comments  cause  org-mode
       nodes  to  be  ignored, allowing emacs users to fold and navigate their
       journals with org-mode or orgstruct-mode.)

       Also,  anything  between  comment  and  end comment  directives  is   a
       (multi-line)  comment.  If there is no end comment, the comment extends
       to the end of the file.

       You can attach comments to a transaction  by  writing  them  after  the
       description  and/or  indented  on the following lines (before the post-
       ings).  Similarly, you can attach comments to an individual posting  by
       writing  them  after the amount and/or indented on the following lines.
       Transaction and posting comments must begin with a semicolon (;).

       Some examples:

              # a file comment

              ; also a file comment

              comment
              This is a multiline file comment,
              which continues until a line
              where the "end comment" string
              appears on its own (or end of file).
              end comment

              2012/5/14 something  ; a transaction comment
                  ; the transaction comment, continued
                  posting1  1  ; a comment for posting 1
                  posting2
                  ; a comment for posting 2
                  ; another comment line for posting 2
              ; a file comment (because not indented)

   Tags
       Tags are a way to add extra labels or labelled  data  to  postings  and
       transactions, which you can then search or pivot on.

       A  simple  tag is a word (which may contain hyphens) followed by a full
       colon, written inside a transaction or posting comment line:

              2017/1/16 bought groceries    ; sometag:

       Tags can have a value, which is the text after the  colon,  up  to  the
       next comma or end of line, with leading/trailing whitespace removed:

                  expenses:food    $10   ; a-posting-tag: the tag value

       Note  this  means  hledger's  tag values can not contain commas or new-
       lines.  Ending at commas means you can write multiple short tags on one
       line, comma separated:

                  assets:checking       ; a comment containing tag1:, tag2: some value ...

       Here,

       o "a comment containing" is just comment text, not a tag

       o "tag1" is a tag with no value

       o "tag2" is another tag, whose value is "some value ..."

       Tags  in  a  transaction  comment affect the transaction and all of its
       postings, while tags in a posting comment  affect  only  that  posting.
       For  example,  the  following  transaction  has  three  tags  (A, TAG2,
       third-tag) and the posting has four (those plus posting-tag):

              1/1 a transaction  ; A:, TAG2:
                  ; third-tag: a third transaction tag, <- with a value
                  (a)  $1  ; posting-tag:

       Tags are like Ledger's metadata feature, except  hledger's  tag  values
       are simple strings.

   Directives
   Account aliases
       You  can define aliases which rewrite your account names (after reading
       the journal, before generating reports).  hledger's account aliases can
       be useful for:

       o expanding shorthand account names to their full form, allowing easier
         data entry and a less verbose journal

       o adapting old journals to your current chart of accounts

       o experimenting with new account organisations, like a new hierarchy or
         combining two accounts into one

       o customising reports

       See also Cookbook: rewrite account names.

   Basic aliases
       To  set an account alias, use the alias directive in your journal file.
       This affects all subsequent journal entries in the current file or  its
       included 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 full account names.  hledger will replace any occur-
       rence of the old account name with the new one.  Subaccounts  are  also
       affected.  Eg:

              alias checking = assets:bank:wells fargo:checking
              # rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"

   Regex aliases
       There  is  also a more powerful variant that uses a regular expression,
       indicated by the forward slashes:

              alias /REGEX/ = REPLACEMENT

       or --alias '/REGEX/=REPLACEMENT'.

       REGEX is a case-insensitive regular expression.   Anywhere  it  matches
       inside  an  account name, the matched part will be replaced by REPLACE-
       MENT.  If REGEX contains parenthesised match groups, these can be  ref-
       erenced by the usual numeric backreferences in REPLACEMENT.  Eg:

              alias /^(.+):bank:([^:]+)(.*)/ = \1:\2 \3
              # rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"

       Also  note that REPLACEMENT continues to the end of line (or on command
       line, to end of option argument), so it  can  contain  trailing  white-
       space.

   Multiple aliases
       You  can  define  as  many aliases as you like using directives or com-
       mand-line options.  Aliases are recursive - each alias sees the  result
       of  applying  previous  ones.   (This  is  different from Ledger, where
       aliases are non-recursive by default).  Aliases are applied in the fol-
       lowing order:

       1. alias  directives,  most recently seen first (recent directives take
          precedence over earlier ones; directives not yet seen are ignored)

       2. alias options, in the order they appear on the command line

   end aliases
       You  can  clear  (forget)  all  currently  defined  aliases  with   the
       end aliases directive:

              end aliases

   account directive
       The  account directive predefines account names, as in Ledger and Bean-
       count.  This may be useful for your own documentation; hledger  doesn't
       make use of it yet.

              ; account ACCT
              ;   OPTIONAL COMMENTS/TAGS...

              account assets:bank:checking
               a comment
               acct-no:12345

              account expenses:food

              ; etc.

   apply account directive
       You  can  specify  a  parent  account  which  will  be prepended to all
       accounts within a section of the journal.  Use  the  apply account  and
       end apply account directives like so:

              apply account home

              2010/1/1
                  food    $10
                  cash

              end apply account

       which is equivalent to:

              2010/01/01
                  home:food           $10
                  home:cash          $-10

       If  end apply account  is  omitted,  the effect lasts to the end of the
       file.  Included files are also affected, eg:

              apply account business
              include biz.journal
              end apply account
              apply account personal
              include personal.journal

       Prior to hledger 1.0, legacy account and end spellings were  also  sup-
       ported.

   Multi-line comments
       A  line containing just comment starts a multi-line comment, and a line
       containing just end comment ends it.  See comments.

   commodity directive
       The commodity directive predefines commodities (currently this is  just
       informational),  and  also it may define the display format for amounts
       in this commodity (overriding the automatically inferred format).

       It may be written on a single line, like this:

              ; commodity EXAMPLEAMOUNT

              ; display AAAA amounts with the symbol on the right, space-separated,
              ; using period as decimal point, with four decimal places, and
              ; separating thousands with comma.
              commodity 1,000.0000 AAAA

       or on multiple lines, using the "format" subdirective.   In  this  case
       the  commodity  symbol  appears  twice  and  should be the same in both
       places:

              ; commodity SYMBOL
              ;   format EXAMPLEAMOUNT

              ; display indian rupees with currency name on the left,
              ; thousands, lakhs and crores comma-separated,
              ; period as decimal point, and two decimal places.
              commodity INR
                format INR 9,99,99,999.00

   Default commodity
       The D directive sets a default commodity (and display  format),  to  be
       used for amounts without a commodity symbol (ie, plain numbers).  (Note
       this differs from Ledger's default commodity directive.) The  commodity
       and  display  format  will  be applied to all subsequent commodity-less
       amounts, or until the next D directive.

              # commodity-less amounts should be treated as dollars
              # (and displayed with symbol on the left, thousands separators and two decimal places)
              D $1,000.00

              1/1
                a     5    ; <- commodity-less amount, becomes $1
                b

   Default year
       You can set a default year to be used for subsequent dates which  don't
       specify  a year.  This is a line beginning with Y followed by the year.
       Eg:

              Y2009      ; set default year to 2009

              12/15      ; equivalent to 2009/12/15
                expenses  1
                assets

              Y2010      ; change default year to 2010

              2009/1/30  ; specifies the year, not affected
                expenses  1
                assets

              1/31       ; equivalent to 2010/1/31
                expenses  1
                assets

   Including other files
       You can pull in the content of additional journal files by  writing  an
       include directive, like this:

              include path/to/file.journal

       If  the path does not begin with a slash, it is relative to the current
       file.  Glob patterns (*) are not currently supported.

       The include directive can only  be  used  in  journal  files.   It  can
       include journal, timeclock or timedot files, but not CSV files.

Periodic transactions
       A  periodic transaction starts with a tilde `~' in place of a date fol-
       lowed by a period expression:

              ~ weekly
                assets:bank:checking   $400 ; paycheck
                income:acme inc

       Periodic transactions are used for budgeting and forecasting only, they
       have  no  effect  without  the --forecast or --budget option specified.
       For examples and details, see Budgeting and Forecasting.

Automated posting rules
       Autopated posting rule starts with an equal sign  `='  in  place  of  a
       date, followed by a query:

              = expenses:gifts
                  budget:gifts  *-1
                  assets:budget  *1

       When  --auto option is specified on the command line, automated posting
       rule will add its postings to all transactions that match the query.

       If amount in the automated posting rule includes  commodity  name,  new
       posting will be made in the given commodity, otherwise commodity of the
       matched transaction will be used.

       When amount in the automated posting rule begins with the  '*',  amount
       will  be  treated  as a multiplier that is applied to the amount of the
       first posting in the matched transaction.

       In example above, every transaction in expenses:gifts account will have
       two  additional  postings added to it: amount of the original gift will
       be debited from budget:gifts and credited into assets:budget:

              ; Original transaction
              2017-12-14
                expenses:gifts  $20
                assets

              ; With automated postings applied
              2017/12/14
                  expenses:gifts             $20
                  assets
                  budget:gifts              $-20
                  assets:budget              $20

EDITOR SUPPORT
       Add-on modes exist for various text editors, to make working with jour-
       nal  files  easier.   They add colour, navigation aids and helpful com-
       mands.  For hledger users who  edit  the  journal  file  directly  (the
       majority), using one of these modes is quite recommended.

       These  were  written  with  Ledger  in mind, but also work with hledger
       files:


       Emacs              http://www.ledger-cli.org/3.0/doc/ledger-mode.html
       Vim                https://github.com/ledger/ledger/wiki/Getting-started
       Sublime Text       https://github.com/ledger/ledger/wiki/Using-Sub-
                          lime-Text
       Textmate           https://github.com/ledger/ledger/wiki/Using-Text-
                          Mate-2
       Text Wrangler      https://github.com/ledger/ledger/wiki/Edit-
                          ing-Ledger-files-with-TextWrangler

       Visual    Studio   https://marketplace.visualstudio.com/items?item-
       Code               Name=mark-hansen.hledger-vscode



REPORTING BUGS
       Report bugs at http://bugs.hledger.org (or on the #hledger IRC  channel
       or hledger mail list)


AUTHORS
       Simon Michael <simon@joyful.com> and contributors


COPYRIGHT
       Copyright (C) 2007-2016 Simon Michael.
       Released under GNU GPL v3 or later.


SEE ALSO
       hledger(1),      hledger-ui(1),     hledger-web(1),     hledger-api(1),
       hledger_csv(5), hledger_journal(5), hledger_timeclock(5), hledger_time-
       dot(5), ledger(1)

       http://hledger.org



hledger 1.4.99                   December 2017              hledger_journal(5)
