Files

Some views and explanations of files in the hledger project.

Repos

The official hledger repos are:

the main repo, https://github.com/hledgerorg/hledger (shortcut: https://code.hledger.org): hledger, hledger-ui and hledger-web code, user manuals, developer docs
the site repo, https://github.com/hledgerorg/hledger_site (https://site.hledger.org): the hledger.org website and additional docs
the finance repo, https://github.com/hledgerorg/hledger_finance (https://finance.hledger.org): the project’s financial journals and reports

Third-party hledger tools and add-ons (hledger-iadd, hledger-flow, etc.) have their own repos; see Scripts and add-ons.

A full working copy of the official repos is best laid out like this (manually; we currently don’t use git submodules):

src/hledger/ - git clone https://github.com/hledgerorg/hledger; cd hledger
  site/      - git clone https://github.com/hledgerorg/hledger_site site
  finance/   - git clone https://github.com/hledgerorg/hledger_finance finance

You don’t need to clone all of these repos unless you are working in all of those areas.

The main repo contains the hledger-lib, hledger, hledger-ui, and hledger-web haskell packages, the hledger-install script, a collection of example data, some documentation and other support files. Some notable locations:

hledger-lib/, hledger/, hledger-ui/, hledger-web/ - the haskell packages; each has a package.yaml, README.md, CHANGES.md and test/
hledger/Hledger/Cli/Commands/ - one module and one doc file per command
hledger/test/ - functional tests (shelltestrunner files), grouped by feature
hledger/embeddedfiles/ - generated docs embedded in the hledger executable
examples/ - sample journals, CSV rules, scripts and other examples (see its README, and Sample journals below)
bin/ - add-on scripts for users (see Scripts)
tools/ - scripts for developers and maintainers
doc/ - developer docs, notes, specs and other project docs
Justfile, Shake.hs - project automation (see DEVWORKFLOWS)
.github/workflows/ - CI and release workflows

To see the current directory tree, run tools/gtree -d in the repo (or tools/gtree REGEX to list matching files).

Sample journals

Synthetic journals like examples/10ktxns-1kaccts.journal are useful for benchmarks and testing. The name gives the number of transactions and the number of accounts (each 10 levels deep). They are generated by tools/generatejournal.hs, and are not committed; just samplejournals (re)generates the standard set.

site repo

The site repo contains the website infrastructure (book.toml, theme/, css/, js/, Makefile), the content source in src/ (including versioned snapshots of the user manuals in src/1.*/), and symlinks to the dev docs and other files kept in the main repo.

book.toml is the main config file for mdbook.
src/SUMMARY.md defines the site’s pages and which ones appear in the sidebar (except for old manual versions; those are rendered separately).

finance repo

The finance repo contains the project’s transaction journals and financial reports.

Core docs

Core documentation which should stay closely synced with hledger’s implementation (changelogs, user manuals, developer docs) is kept in the main repo.

Many directories have a README.md explaining their purpose and content.
Each hledger package, and the project itself, has a CHANGES.md changelog file.
hledger/hledger.m4.md, hledger-ui/hledger-ui.m4.md, hledger-web/hledger-web.m4.md are the user manuals, which get rendered as html, info, man and plain text. They are processed first with m4 for extra flexibility.
The hledger manual imports the subcommand docs from hledger/Hledger/Cli/Commands/*.md.
doc/ contains other developer docs. See DOCS for more.

Keyboard shortcuts