From 9418807ddc4c8461fe6997ad6e4597943d62f995 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Fri, 11 Jul 2025 10:17:30 -0700 Subject: [PATCH] ;doc: include directive: clarify effect, glob limitations --- hledger/hledger.m4.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md index f82ff2282..fb77c5744 100644 --- a/hledger/hledger.m4.md +++ b/hledger/hledger.m4.md @@ -2509,29 +2509,33 @@ file contains digit group marks (eg thousands separators). You can pull in the content of additional files by writing an include directive, like this: ```journal -include FILEPATH +include SOMEFILE ``` -Only journal files can include, and only journal, timeclock or timedot files can be included (not CSV files, currently). +This has the same effect as if SOMEFILE's content was inlined at this point. +(Any `include`s within SOMEFILE will also be inlined, recursively.) -If the file path does not begin with a slash, it is relative to the current file's folder. +Only journal files can include other files. +They can include journal, timeclock or timedot files, but not CSV files. -A tilde means home directory, eg: `include ~/main.journal`. +If the file path begins with a tilde, that means home directory: `include ~/main.journal`. + +If it begins with a slash, it is an absolute path: `include /home/user/main.journal`. + +Otherwise it is relative to the current file's folder: `include finances/main.journal`. + +Also, the path may have a file type prefix to force a specific file format +(as described in [Data formats](#data-formats)): `include timedot:~/notes/2023*.md`. The path may contain [glob patterns] to match multiple files, eg: `include *.journal`. -There is limited support for recursive wildcards: `**/` (the slash is required) -matches 0 or more subdirectories. It's not super convenient since you have to -avoid include cycles and including directories, but this can be done, eg: -`include */**/*.journal`. - -The path may also be prefixed to force a specific file format, -overriding the file extension (as described in -[Data formats](#data-formats)): -`include timedot:~/notes/2023*.md`. +The special glob pattern `**/` matches any number of directory parts. +This is not robust; it can hang, and `**/*.journal` is rejected. +But this will work: `include */**/*.journal` (find all .journal files below the current directory). [glob patterns]: https://hackage.haskell.org/package/Glob-0.9.2/docs/System-FilePath-Glob.html#v:compile + ## `P` directive The `P` directive declares a market price, which is