Handling File Paths for Beancount Document Directives Across Different Devices
KD D
I’m relatively new to Beancount and I’m working on setting up my ledgers. I’ve encountered an issue related to document directives when dealing with different devices. Here’s a breakdown of my situation and the potential solutions I’ve considered:
- I have started writing my importers for filing various statements (using the beangulp framework).
- As part of the import, I’d like to extract and output a document directive.
- I am using document directives as opposed to the option "documents" "PathToRoot" because I’d like to add metadata to the document directive entries.
Beancount Document directives have the following construct: YYYY-MM-DD document Account "PathToDocument".
Let us assume that we have two users, Joe and Alice, who run a shared ledger that is kept on GitHub. They store their statements and other document files on a shared OneDrive folder that is synced to each users computer.
Alice’s file organization:
/home/alice/ |-- OneDrive |-- documents |-- stmts |-- Liabilities |-- CreditCard |-- apr-2014.pdf |-- etc., |-- remotes |-- ledger |-- main.beancountJoe’s file organization:
/home/joe/ |-- OneDrive |-- documents |-- stmts |-- Liabilities |-- CreditCard |-- apr-2014.pdf |-- etc., |-- remotes |-- ledger |-- main.beancountIf Joe files the apr-2014.pdf statement, he would enter the following into main.beancount:
2013-11-03 document Liabilities:CreditCard "/home/joe/OneDrive/documents/stmts/apr-2014.pdf"On Alice’s computer, however, this would be the incorrect file path. For Alice, the entry should read:
2013-11-03 document Liabilities:CreditCard "/home/alice/OneDrive/documents/stmts/apr-2014.pdf"This causes issues and prevents the Alice and Joe from being able to use the ledgers properly (bean-check will fail since the file is not found).
Potential SolutionsI have tried to do some research on how one might address this issue. I have come upon three potential options:
Use relative paths
Instead of entering the absolute path, use a relative path such that the document directive becomes:
2013-11-03 document Liabilities:CreditCard "../../OneDrive/documents/stmts/apr-2014.pdf"This looks like it would work, provided Alice and Joe keep their documents in the exact same place relative to the ledger file. That seems a bit fragile and not so elegant.
Use a symlinked folder
Each user could add a symlinked documents folder into the main ledger folder, for example:
|-- remotes |-- ledger |-- main.beancount |-- documents --> /home/joe/OneDrive/documentsThis solution seems better, since it allows each user to specify their own folder path.
Run a pre-processing script
Each user could run a pre-processing script on the ledger files to replace a set of placeholder variables with the locally configured variables. The updated file would then become the input to the beancount parser. For example:
2013-11-03 document Liabilities:CreditCard "$DOCUMENT_PATH/stmts/apr-2014.pdf"This could work, but it introduces an additional layer of complexity, as users would need to run this script before parsing the ledger file.
What I would like to know is:
Are there any alternative options that I have failed to consider here?
For example, is there the chance that Beancount itself could recognise a configuration variable that represents the root documents directory? Could this be declared as an option in the main ledger file?
If there are no other possibilities, does anyone have any advice on which approach is best?
