How to Use the Command 'hledger print' (with examples)

The hledger print command is part of the Hledger suite of tools that facilitate personal and business accounting management using plain text files. This command is used to display full journal entries from a ledger file, enabling users to review transactions in a comprehensive manner. Whether you’re handling personal finances or managing business accounts, hledger print provides a flexible approach to understand and analyze financial data by showcasing transactions with an array of customizable options. Below are different use cases of the hledger print command, highlighting its various functionalities.

Use case 1: Show all transactions in the default journal file

Code:

hledger print

Motivation: This is the most straightforward use case of the hledger print command. Running it without any additional options will print all the transactions recorded in the default journal file. This option is useful for individuals or small businesses wishing to review all financial transactions in one place without needing advanced filtering.

Explanation:

• hledger print: This command fetches and displays all the transactions from the journal file set as the default. If no default file is specified, it usually looks for a file named hledger.journal in the current directory.

Example Output:

2023/01/01 Salary
    Assets:Bank:Checking                   $1000
    Income:Salary

2023/01/02 Grocery
    Expenses:Food:Groceries                $150
    Assets:Bank:Checking

Use case 2: Show transactions, with any implied amounts or costs made explicit

Code:

hledger print --explicit --infer-costs

Motivation: This command is useful when the journal contains transactions with amounts or costs that need to be fully explicit. It helps account for any implied information that might not be initially clear within the journal entries. This is important for maintaining transparency, especially in complex financial journals where transaction amounts may be inferred rather than specified outright.

Explanation:

• --explicit: This option ensures that all implied transaction amounts are made explicit, so every quantity in the transaction is clearly stated.
• --infer-costs: This option calculates and displays costs that might be implicit within the transactions by examining commodity transactions and applying existing price directives.

Example Output:

2023/01/01 Salary
    Assets:Bank:Checking                   $1000
    Income:Salary

2023/01/02 Grocery (firewood) @ $10
    Expenses:Food:Groceries                $150 @ $1.50
    Assets:Bank:Checking

Use case 3: Show transactions from two specified files, with amounts converted to cost

Code:

hledger print --file path/to/2023.journal --file path/to/2024.journal --cost

Motivation: This use case is instrumental when one needs to consolidate transactions from two different journal files for review, particularly when comparing transactions over two fiscal years. Specifying the conversion to costs allows for accurate tracking of financial expenses and adjustments in value over time.

Explanation:

• --file path/to/2023.journal: Specifies the first journal file from which transactions will be printed.
• --file path/to/2024.journal: Specifies the second journal file for transactions which need comparison with the first.
• --cost: Converts all amounts into a consistent cost basis, which helps simplify understanding net financial movements between varying financial periods.

Example Output:

2023/01/01 Asset Purchase
    Assets:Equipment                       $500 cost $480
    Liabilities:Loans

2024/01/01 Asset Depreciation
    Expenses:Depreciation                  $100 cost $95
    Assets:Equipment

Use case 4: Show $ transactions in *food* but not *groceries* accounts this month

Code:

hledger print cur:\$ food not:groceries date:thismonth

Motivation: This syntax is advantageous for users who need to audit their food expenses, excluding specific categories like groceries, within the current calendar month. It helps isolate specific financial areas one wants to review by filtering and excluding certain account contexts when printing.

Explanation:

• cur:\$: Filters to show only transactions involving currency in dollars.
• food: Filters to include only transactions tagged to food-related expense accounts.
• not:groceries: Excludes transactions linked with the groceries accounts within the food category.
• date:thismonth: Restricts transactions to those dated within the current month only.

Example Output:

2023/09/15 Restaurant
    Expenses:Food:DiningOut                $75
    Assets:Bank:Checking

Use case 5: Show transactions of amount 50 or more, with whole foods in their description

Code:

hledger print amt:'>50' desc:'whole foods'

Motivation: When auditing specific high-value transactions or monitoring spending habits concerning particular establishments like Whole Foods, this command helps by filtering transactions above a certain monetary threshold with descriptions matching “whole foods.” This can be used for budget tracking or expense reporting.

Explanation:

• amt:'>50': Filters to display only transactions where the amount is greater than $50.
• desc:'whole foods': Searches for transactions that include the description “whole foods.”

Example Output:

2023/09/20 Whole Foods Purchase
    Expenses:Groceries                      $125
    Assets:Bank:Savings

Use case 6: Show cleared transactions, with EUR amounts rounded and with decimal commas

Code:

hledger print --cleared --commodity '1000, EUR' --round hard

Motivation: This command is used when specific reporting requirements demand that transactions are cleared (confirmed and completed) and need to display currency amounts in a format characterized by thousand separators and decimal commas, often a format used in several European countries.

Explanation:

• --cleared: Shows only transactions that have been cleared from the account.
• --commodity '1000, EUR': Formats displayed amounts with thousand separators and the currency sign in euros.
• --round hard: Rounds the displayed figures to the nearest whole number using a “hard” rounding mechanism, simplifying studies or presentations of the financial data.

Example Output:

2023/09/21 Cleared Transaction
    Assets:Bank:Checking                   €1.000,00
    Expenses:Utilities

Use case 7: Write transactions from foo.journal as a CSV file

Code:

hledger print --file path/to/foo.journal --output-file path/to/output_file.csv

Motivation: Converting financial records to CSV format allows for broader analysis and presentation capabilities, including importing into spreadsheets and databases. This makes it easy to work with the data outside the limitations of text-based journal files, facilitating sharing or analysis in applications like Excel, Google Sheets, or custom software.

Explanation:

• --file path/to/foo.journal: Specifies the input journal file from which transactions are extracted.
• --output-file path/to/output_file.csv: Specifies the output path and filename where the transactions will be written in CSV format.

Example Output:

Date,Description,Account,Amount,Commodity
2023/09/15,Dining Out,Expenses:Food,75,USD
2023/09/20,Whole Foods Purchase,Expenses:Groceries,125,USD

Conclusion:

The hledger print command exemplifies versatility in managing financial data by offering a range of functionalities to display, filter, and convert journal entries. From elementary applications such as printing all transactions to advanced tasks like converting them to CSV format, the command adapts to various financial analysis needs. The broad set of options allows users to tailor their approach for detailed transaction feedback, making hledger print a vital tool for efficient financial tracking and management.