This is hledger_csv.5.info, produced by makeinfo version 6.0 from stdin.


File: hledger_csv.5.info,  Node: Top,  Next: CSV RULES,  Up: (dir)

hledger_csv(5) hledger 1.3
**************************

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.
* Menu:

* CSV RULES::
* CSV TIPS::


File: hledger_csv.5.info,  Node: CSV RULES,  Next: CSV TIPS,  Prev: Top,  Up: Top

1 CSV RULES
***********

The following seven kinds of rule can appear in the rules file, in any
order.  Blank lines and lines beginning with '#' or ';' are ignored.
* Menu:

* skip::
* date-format::
* field list::
* field assignment::
* conditional block::
* include::
* newest-first::


File: hledger_csv.5.info,  Node: skip,  Next: date-format,  Up: CSV RULES

1.1 skip
========

'skip'_'N'_

   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


File: hledger_csv.5.info,  Node: date-format,  Next: field list,  Prev: skip,  Up: CSV RULES

1.2 date-format
===============

'date-format'_'DATEFMT'_

   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


File: hledger_csv.5.info,  Node: field list,  Next: field assignment,  Prev: date-format,  Up: CSV RULES

1.3 field list
==============

'fields'_'FIELDNAME1'_, _'FIELDNAME2'_...

   This (a) names the CSV fields, in order (names may not contain
whitespace; 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


File: hledger_csv.5.info,  Node: field assignment,  Next: conditional block,  Prev: field list,  Up: CSV RULES

1.4 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.


File: hledger_csv.5.info,  Node: conditional block,  Next: include,  Prev: field assignment,  Up: CSV RULES

1.5 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
regular 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


File: hledger_csv.5.info,  Node: include,  Next: newest-first,  Prev: conditional block,  Up: CSV RULES

1.6 include
===========

'include'_'RULESFILE'_

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

# rules reused with several CSV files
include common.rules


File: hledger_csv.5.info,  Node: newest-first,  Prev: include,  Up: CSV RULES

1.7 newest-first
================

'newest-first'

   Consider adding this rule if: your CSV records are in reverse
chronological order (newest first), and you care about preserving the
order of same-day transactions, and you might be processing just one day
of data.  It usually isn't needed, because hledger autodetects the CSV
order, but if all the CSV records have the same date it assumes they are
oldest first.


File: hledger_csv.5.info,  Node: CSV TIPS,  Prev: CSV RULES,  Up: Top

2 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
'balance' pseudo field to generate a balance assertion on 'account1'
whenever the balance field is non-empty.  (Eg to double-check your
bank's balance 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.


Tag Table:
Node: Top74
Node: CSV RULES810
Ref: #csv-rules920
Node: skip1182
Ref: #skip1278
Node: date-format1450
Ref: #date-format1579
Node: field list2085
Ref: #field-list2224
Node: field assignment2929
Ref: #field-assignment3086
Node: conditional block3590
Ref: #conditional-block3746
Node: include4642
Ref: #include4774
Node: newest-first5005
Ref: #newest-first5121
Node: CSV TIPS5504
Ref: #csv-tips5600

End Tag Table
