Skip to content

Commit

Permalink
;doc: journal cheatsheet cleanups
Browse files Browse the repository at this point in the history
  • Loading branch information
@simonmichael
simonmichael committed Mar 3, 2024
1 parent 878ebac commit 5def834
Showing 1 changed file with 111 additions and 71 deletions.
182 changes: 111 additions & 71 deletions hledger/hledger.m4.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -815,91 +815,131 @@ Here's a quick cheatsheet/overview, followed by detailed descriptions of each pa
```journal
# 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
# 1. These are comment lines, for notes or temporarily disabling things.
; They begin with # or ;
comment
These lines
are commented.
Or, lines can be enclosed within "comment" / "end comment".
This is a block of
commented lines.
end comment
# Some but not all hledger entries can have same-line comments attached to them,
# from ; (semicolon) to end of line.
# Some journal entries can have semicolon comments at end of line ; like this
# Some of them require 2 or more spaces before the semicolon.
###############################################################################
# 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
# 2. Directives customise processing or output in some way.
# You don't need any directives to get started.
# But they can add more error checking, or change how things are displayed.
# They begin with a word, letter, or symbol.
# They are most often placed at the top, before transactions.
account assets ; Declare valid account names and display order.
account assets:savings ; A subaccount. This one represents a bank account.
account assets:checking ; Another. Note, 2+ spaces after the account name.
account assets:receivable ; Accounting type is inferred from english names,
account passifs ; or declared with a "type" tag, type:L
account expenses ; type:X
; A follow-on comment line, indented.
account expenses:rent ; Expense and revenue categories are also accounts.
; Subaccounts inherit their parent's type.
commodity $0.00 ; Declare valid commodities and their display styles.
commodity 1.000,00 EUR
decimal-mark . ; The decimal mark used in this file (if ambiguous).
payee Whole Foods ; Declare a valid payee name.
tag trip ; Declare a valid tag name.
P 2024-03-01 AAPL $179 ; Declare a market price for AAPL in $ on this date.
include other.journal ; Include another journal file here.
# Declare a recurring "periodic transaction", for budget/forecast reports
~ monthly set budget goals ; <- Note, 2+ spaces before the description.
(expenses:rent) $1000
(expenses:food) $500
# Declare an auto posting rule, to modify existing transactions in reports
= revenues:consulting
liabilities:tax:2024:us *0.25 ; Add a tax liability & expense
expenses:tax:2024:us *-0.25 ; for 25% of the revenue.
###############################################################################
# 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
# 3. Transactions are what it's all about.
# They are dated events, usually movements of money between 2 or more accounts.
# They begin with a numeric date.
# Here is their basic shape:
#
# DATE DESCRIPTION ; The transaction's date and optional description.
# ACCOUNT1 AMOUNT ; A posting of an amount to/from this account, indented.
# ACCOUNT2 AMOUNT ; A second posting, balancing the first.
# ... ; More if needed. Amounts must sum to zero.
# ; Note, 2+ spaces between account names and amounts.
2024-01-01 opening balances ; At the start, declare pre-existing balances this way.
assets:savings $10000 ; Account names can be anything. lower case is easy to type.
assets:checking $1000 ; assets, liabilities, equity, revenues, expenses are common.
liabilities:credit card $-500 ; liabilities, equity, revenues balances are usually negative.
equity:start ; One amount can be left blank. $-10500 is inferred here.
; Some of these accounts we didn't declare above,
; so -s/--strict would complain.
2024-01-03 ! (12345) pay rent
; Additional transaction comment lines, indented.
; 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"
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.
; There can be a parenthesised (code) after the date/status.
; Amounts' sign shows direction of flow.
assets:checking $-500 ; Minus means removed from this account (credit).
expenses:rent $500 ; Plus means added to this account (debit).
; Keeping transactions in date order is optional (but helps error checking).
2024-01-02 Gringott's Bank | withdrawal ; Description can be PAYEE | NOTE
assets:bank:gold -10 gold
assets:pouch 10 gold
2024-01-02 shopping
expenses:clothing 1 gold
expenses:wands 5 gold
assets:pouch -6 gold
2024-01-02 receive gift
revenues:gifts -3 "Chocolate Frogs" ; Complex commodity symbols
assets:pouch 3 "Chocolate Frogs" ; must be in double quotes.
2024-01-15 buy some shares, in two lots ; Cost can be noted.
assets:investments:2024-01-15 2.0 AAAA @ $1.50 ; @ means per-unit cost
assets:investments:2024-01-15-02 3.0 AAAA @@ $4 ; @@ means total cost
; ^ Per-lot subaccounts are sometimes useful.
assets:checking $-7
2024-01-15 assert some account balances on this date
; Balances can be asserted in any transaction, with =, for extra error checking.
; Assertion txns like this one can be made with hledger close --assert --show-costs
;
assets:savings $0 = $10000
assets:checking $0 = $493
assets:bank:gold 0 gold = -10 gold
assets:pouch 0 gold = 4 gold
assets:pouch 0 "Chocolate Frogs" = 3 "Chocolate Frogs"
assets:investments:2024-01-15 0.0 AAAA = 2.0 AAAA @ $1.50
assets:investments:2024-01-15-02 0.0 AAAA = 3.0 AAAA @@ $4
liabilities:credit card $0 = $-500
2024-02-01 note some event, or a transaction not yet fully entered, on this date
; 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).
; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful).
2024.01.01
2024/1/1
```

## Comments
Expand Down

0 comments on commit 5def834

Please sign in to comment.