
hledger_csv(5)               hledger User Manuals               hledger_csv(5)



NAME
       CSV - how hledger reads CSV data, and the CSV rules file format

DESCRIPTION
       hledger  can  read CSV files, converting each CSV record into a journal
       entry (transaction), if you provide some conversion hints in  a  "rules
       file".   This file should be named like the CSV file with an additional
       .rules suffix (eg: mybank.csv.rules); or, you can specify the file with
       --rules-file PATH.   hledger  will  create  it  if necessary, with some
       default rules which you'll need to adjust.  At minimum, the rules  file
       must specify the date and amount fields.  For an example, see Cookbook:
       convert CSV files.

       To learn about exporting CSV, see CSV output.

CSV RULES
       The following six kinds of rule can appear in the rules  file,  in  any
       order.  Blank lines and lines beginning with # or ; are ignored.

   skip
       skipN

       Skip  this  number  of  CSV records at the beginning.  You'll need this
       whenever your CSV data contains header lines.  Eg:

              # ignore the first CSV line
              skip 1

   date-format
       date-formatDATEFMT

       When your CSV  date  fields  are  not  formatted  like  YYYY/MM/DD  (or
       YYYY-MM-DD  or YYYY.MM.DD), you'll need to specify the format.  DATEFMT
       is a strptime-like date parsing pattern,  which  must  parse  the  date
       field values completely.  Examples:

              # for dates like "6/11/2013":
              date-format %-d/%-m/%Y

              # for dates like "11/06/2013":
              date-format %m/%d/%Y

              # for dates like "2013-Nov-06":
              date-format %Y-%h-%d

              # for dates like "11/6/2013 11:32 PM":
              date-format %-m/%-d/%Y %l:%M %p

   field list
       fieldsFIELDNAME1, FIELDNAME2...

       This  (a)  names the CSV fields, in order (names may not contain white-
       space; uninteresting names may be left blank), and (b) assigns them  to
       journal  entry  fields  if  you  use any of these standard field names:
       date, date2, status, code, description,  comment,  account1,  account2,
       amount, amount-in, amount-out, currency, balance.  Eg:

              # use the 1st, 2nd and 4th CSV fields as the entry's date, description and amount,
              # and give the 7th and 8th fields meaningful names for later reference:
              #
              # CSV field:
              #      1     2            3 4       5 6 7          8
              # entry field:
              fields date, description, , amount, , , somefield, anotherfield

   field assignment
       ENTRYFIELDNAME FIELDVALUE

       This  sets  a  journal entry field (one of the standard names above) to
       the given text value, which can include CSV field  values  interpolated
       by name (%CSVFIELDNAME) or 1-based position (%N).
        Eg:

              # set the amount to the 4th CSV field with "USD " prepended
              amount USD %4

              # combine three fields to make a comment (containing two tags)
              comment note: %somefield - %anotherfield, date: %1

       Field  assignments  can  be  used  instead of or in addition to a field
       list.

   conditional block
       if PATTERN
           FIELDASSIGNMENTS...

       if
       PATTERN
       PATTERN...
           FIELDASSIGNMENTS...

       This applies one or more field assignments, only to those  CSV  records
       matched by one of the PATTERNs.  The patterns are case-insensitive reg-
       ular expressions which match anywhere within the whole CSV record (it's
       not  yet  possible  to  match within a specific field).  When there are
       multiple patterns they can be written on  separate  lines,  unindented.
       The  field  assignments  are on separate lines indented by at least one
       space.  Examples:

              # if the CSV record contains "groceries", set account2 to "expenses:groceries"
              if groceries
               account2 expenses:groceries

              # if the CSV record contains any of these patterns, set account2 and comment as shown
              if
              monthly service fee
              atm transaction fee
              banking thru software
               account2 expenses:business:banking
               comment  XXX deductible ? check it

   include
       includeRULESFILE

       Include another rules file at this point.  RULESFILE is either an abso-
       lute file path or a path relative to the current file's directory.  Eg:

              # rules reused with several CSV files
              include common.rules

CSV TIPS
       Each generated journal entry will have two postings,  to  account1  and
       account2 respectively.  Currently it's not possible to generate entries
       with more than two postings.

       If the CSV has debit/credit amounts in separate fields, assign  to  the
       amount-in and amount-out pseudo fields instead of amount.

       If  the  CSV  has  the currency in a separate field, assign that to the
       currency pseudo field which will  be  automatically  prepended  to  the
       amount.  (Or you can do the same thing with a field assignment.)

       If  the CSV includes a running balance, you can assign that to the bal-
       ance pseudo field to generate a balance assertion on account1  whenever
       the  balance  field is non-empty.  (Eg to double-check your bank's bal-
       ance calculation.)

       If an amount value is parenthesised, it will  be  de-parenthesised  and
       sign-flipped automatically.

       The  generated  journal  entries  will be sorted by date.  The original
       order of same-day entries will be preserved, usually.



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.3                        June 2017                    hledger_csv(5)
