monthly-migration

Monthly Migration Skill

Guide for migrating journals at the start of each month.

When to Use

• Start of each month (typically 1st-3rd) before adding new transactions
• Previous month is complete and validated
• Setting up opening/closing balances

Prerequisites

• All transactions for previous month finalized
• Both self.journal and self.alternatives.journal need migration
• Ran python -m check successfully

Process

1. Run Migration Commands

Close both journal types:

# Example: Close December 2025, prepare for January 2026
hledger close -f ledger/2025/2025-12/self.journal --migrate
hledger close -f ledger/2025/2025-12/self.alternatives.journal --migrate

Run separately—one per journal file.

2. Understand Output

hledger close --migrate generates two transactions:

1. Closing balances: Zeroes all accounts at month-end

   2025-12-31 closing balances  ; time: 23:59:59
       assets:banks:<uuid>:HKD     -5000.00 HKD = 0.00 HKD
       ...
       equity:opening/closing balances
   

2. Opening balances: Re-establishes for new month

   2026-01-01 opening balances  ; time: 00:00:00
       assets:banks:<uuid>:HKD      5000.00 HKD = 5000.00 HKD
       ...
       equity:opening/closing balances
   

3. Add Closing to Old Month

Copy closing balances to end of previous month journal.

4. Create New Monthly Journal

If new month directory doesn't exist:

mkdir ledger/2026/2026-01
New-Item ledger/2026/2026-01/self.journal

Include prelude:

include ../../../preludes/self.journal

5. Add Opening to New Month

Copy opening balances to start of new month (after prelude).

6. Adjust Times if Needed

Verify dates/times are correct:

• Closing: last day of month at 23:59:59
• Opening: first day of month at 00:00:00

7. Validate

python -m check
python -m format

8. Commit

git commit -S -m "chore(migration): migrate journals to 2026-01"

Do's and Don'ts

Do:

• Run for both self.journal and self.alternatives.journal
• Create new directory/file if needed
• Include prelude in new journal
• Verify closing balances show = 0.00 CURRENCY
• Run check and format after

Don't:

• Edit hledger close output extensively
• Forget prelude include
• Skip validation before commit
• Perform migration multiple times for same month

Reference Recent Examples

cat ledger/2025/2025-12/self.journal | tail -50  # View closing
cat ledger/2026/2026-01/self.journal | head -50  # View opening

Related Documentation

• Architecture - Journal structure
• Common Workflows - Other workflows
• Editing Guidelines - Best practices