Skip to content

hledger Syntax Specification

This document defines the syntax for hledger journal files.

File Structure

An hledger journal file consists of: - Directives (account, commodity, include, etc.) - Transactions - Comments - Whitespace

Comments

Line Comments

; Semicolon comment
# Hash comment
* Asterisk comment (org-mode style)

End-of-Line Comments

2024-01-15 Groceries  ; Comment on transaction
    Expenses:Food    $50  ; Comment on posting
    Assets:Checking

Block Comments

comment
This is a block comment.
Multiple lines are allowed.
end comment

Dates

Date Formats

2024-01-15    ; ISO format (preferred)
2024/01/15    ; Slash format
2024.01.15    ; Dot format

Secondary Dates

2024-01-15=2024-01-20 Payment  ; Posting date on right

Transactions

Basic Structure

DATE [STATUS] [CODE] DESCRIPTION
    ACCOUNT  AMOUNT
    ACCOUNT  [AMOUNT]

Examples

2024-01-15 Groceries
    Expenses:Food    $50.00
    Assets:Checking

2024-01-15 * (#123) Cleared purchase
    Expenses:Shopping    $100.00
    Liabilities:CreditCard

2024-01-15 ! Pending transfer
    Assets:Savings    $500.00
    Assets:Checking

Status Markers

Marker Meaning Aliases
(none) Unmarked
! Pending
* Cleared

Transaction Codes

Optional code in parentheses:

2024-01-15 (#12345) Check payment
    Expenses:Rent    $1500
    Assets:Checking

Accounts

Account Names

  • Colon-separated segments
  • Case-sensitive
  • Unicode allowed
Assets:Bank:Checking
Liabilities:Credit Cards:Visa
Expenses:Food & Dining:Restaurants

Reserved Top-Level Accounts

By convention: - Assets - Liabilities - Equity - Income (or Revenue) - Expenses

Amounts

Basic Amounts

$100.00
100.00 USD
EUR 100,00
1,234.56 USD

Commodity Placement

$100       ; Symbol before
100 USD    ; Code after
EUR 100    ; Symbol before (European)

Negative Amounts

-$100.00
$-100.00
-100.00 USD

Thousand Separators

$1,234,567.89    ; US style
1.234.567,89 EUR ; European style
1 234 567.89 USD ; Space separator

Amount Inference

One posting per commodity can omit its amount:

2024-01-15 Grocery
    Expenses:Food    $50
    Assets:Checking       ; Inferred as -$50

Prices

Per-Unit Price (@)

    Assets:Investments    10 AAPL @ $150.00

Total Price (@@)

    Assets:EUR    100 EUR @@ $110.00

Balance Assertions

Single-Commodity Assertion (=)

    Assets:Checking    $100 = $1500
    ; Assert Checking has exactly $1500

Subaccount-Inclusive Assertion (=*)

    Assets:Bank    $0 =* $5000
    ; Assert Assets:Bank and all subaccounts total $5000

Zero Balance Check

    Assets:Checking    $0 = $0
    ; Verify account is empty

Balance Assignments

Auto-Calculate Posting

    Assets:Checking    = $1000
    ; Set balance TO $1000, calculate required amount
    Income:Adjustment

Virtual Postings

Unbalanced Virtual (Parentheses)

    (Budget:Food)    $-50
    ; Not included in transaction balance

Balanced Virtual (Brackets)

    [Budget:Food]    $-50
    [Budget:Groceries]    $50
    ; Must balance with other [] postings

Posting Dates

Inline Date

2024-01-15 Payment
    Expenses:Bill    $100  ; date:2024-01-20
    Assets:Checking

Secondary Date Syntax

    Expenses:Bill    $100  ; [2024-01-20]

Tags

Inline Tags

2024-01-15 Groceries  ; project:home, category:food
    Expenses:Food    $50
    Assets:Checking

Tag Syntax

name:value    ; Tag with value
name:         ; Tag without value (empty)

Transaction Tags

Apply to entire transaction:

2024-01-15 Purchase
    ; project:renovation
    Expenses:Materials    $100
    Assets:Checking

Posting Tags

Apply to specific posting:

2024-01-15 Purchase
    Expenses:Materials    $100  ; location:store-a
    Assets:Checking

Whitespace Rules

Indentation

  • Postings MUST be indented
  • Minimum: 1 space
  • Convention: 2 or 4 spaces

Amount Alignment

2024-01-15 Groceries
    Expenses:Food:Groceries     $50.00
    Expenses:Food:Snacks        $10.00
    Assets:Checking            $-60.00

Two-Space Separator

At least two spaces between account and amount:

    Expenses:Food  $50.00    ; Correct: 2 spaces
    Expenses:Food $50.00     ; WRONG: 1 space

Multi-Line Descriptions

Not directly supported. Use comments for continuation:

2024-01-15 Purchase at store
    ; Additional details here
    Expenses:Shopping    $100
    Assets:Checking

Character Encoding

  • UTF-8 is the default encoding
  • BOM is optional but supported
  • Line endings: LF or CRLF

Special Characters

In Account Names

Allowed: letters, numbers, spaces, symbols except: - ; (starts comment) - [ ] (virtual postings) - ( ) (virtual postings)

Escaping

No escape sequences. Use Unicode directly.

Grammar Summary

journal = { entry } ;

entry = transaction
      | directive
      | comment
      | blank_line ;

transaction = date [ secondary_date ] [ status ] [ code ] description newline
              { posting } ;

posting = indent [ status ] account [ amount ] [ assertion ] [ comment ] newline ;

date = year "-" month "-" day
     | year "/" month "/" day
     | year "." month "." day ;

status = "*" | "!" ;

code = "(" text ")" ;

amount = [ "-" ] [ commodity ] number [ commodity ] ;

assertion = "=" amount
          | "=*" amount ;

See Also