support a configuration file ?

[alensiljak]

I tend to heavily utilize .ledgerrc files. Usually to specify the file to use from that folder, or common options if using files for time tracking, time periods, etc. I find it very convenient. It is interesting that hledger's documentation does not mention this nor does hledger apply the commands stored in .ledgerrc files.

I would, therefore, propose that this file is included in execution. Hledger's implementation of time reports is fantastic and it would be very convenient to run them, i.e. for the current week, by including the common specs in the rc file (time period, journal file) and just executing hledger, for example.

[simonmichael]

Until now hledger is config file free, which simplifies implementation, learning, troubleshooting, support, etc.

I usually define custom hledger commands in ./bashrc (source bashrc; CMD) or ./Makefile (make CMD).

I didn't know you could have per-folder .ledgerrc files; that sounds nice for some situations, and more portable than the above.

Here's a way to emulate a per-directory config file (in bash). The script uses ./.hledger as an argument file if present:

$ function h() { [[ -e .hledger ]] && hledger @.hledger "$@" || hledger "$@" ; }
$ h files
/Users/simon/notes/2019.journal
$ echo "-ftime-2019.timedot" > .hledger
$ h files
/Users/simon/notes/time-2019.timedot

If you feel it's worth adding better config file support, help us design it, and try to attract supporters to this issue. Questions include:

• which config files to load - current directory ? parent directories ? home directory ? where in home directory ?
• which config file name(s) to recognise ?
• content and syntax of config files ? should they be distinct from regular data files ?
• attempt to load ledger config files ?
• is a flag needed for disabling config files ? disable some of them, or all ?
• clarify the real problems this solves; are the benefits sufficient ?

[khass1]

Simon,

It would be better to follow ledger approach with this issue, I’ll try to answer the questions you wrote below.

• which config files to load - current directory ? parent directory ? home directory ? where in home directory ?

On ledger you can invoke the -i directive and load another file before the .ledgerrc file is loaded from ~/

• which config file name(s) to recognise ?

.hledgerrc would be fine

• content and syntax of config files ? 

Each line in the .ledgerrc file is separated by a line, this should work for hledger too

• attempt to load ledger config files ?

Yes. Both programs share similar commands

• is a flag needed for disabling config files ? disable some of them, or all ?

Yes, ledger has the directive --args-only that disables the init file loading

• clarify the real problems this solves; are the benefits sufficient ?

On my use case I want to use only one price.db file for all files and I can point the path on the init file. Also I want to use the directives —effective and —sort date for all commands. It saves time as it’s not needed to write them all the time

[simonmichael]

Thanks for the input. I think that use case is about: using a user-level config file for setting options that you want to use always with all hledger commands.

Re attempting to load Ledger configs, that example wouldn't work with hledger, which doesn't accept those options.

[simonmichael]

When you want to turn off one of those options, I guess you have to use --args-only.

[alensiljak]

Thank you for the feedback. As mentioned, I find these very useful and flexible. For longer commands I create specific shell scripts to execute regular reports but for shorter and more random queries, these really come in handy. Specifying a book (ledger file or a collection), for example, or date format (this one is a good candidate for the home folder config file which applies globally), or price database which I want to use from different folders, etc. This cuts the typed commands significantly and helps focus on what I want to get out while typing the command-line query. Let me answer your questions for the moment and hopefully, with some more input, this could be a flexible and convenient feature that would help others.

• which config files to load - current directory ? parent directories ? home directory ? where in home directory ? I like how ledger does it. Simply because this is not something I came up with but was excited with the simplicity and the flexibility it offers. It's still too early a stage for me to have ideas on top of that. Plus, it would be nice if the application of the config files was similar to avoid the mental shift when utilizing different applications with the same set of data (books). So, using the local folder, then home folder, would probably be sufficient. Home folder for globals (like the data format, for example), and local for the book, custom output format, price database, and so on.
• which config file name(s) to recognise ? If the syntax is different, as you say, then .hledgerrc makes sense. See below for . ledgerrc.
• content and syntax of config files ? should they be distinct from regular data files ? Oh, yes. These are just the parameters and options one would normally type in the command line.
• attempt to load ledger config files ? Absolutely. Apply only the directives/filters/options which apply to hledger and list them somewhere for reference. Ignore others or print out a warning that it is ignored so that this is transparent to the user. This might cause some confusion as there are parameters with the same syntax but different semantics but that might be circumvented by knowing that the options are coming from a ledger config. Would the options with the same syntax then require .hledger config? This one might be added to .ledgerrc, overwriting any option with the same syntax, just like the command line options overwrite the ones from the config, and a local config overwrites the global.
• is a flag needed for disabling config files ? disable some of them, or all ? Hm. Too much for me at this stage. Normally, it is not too hard to change a folder and run the same commands, to ignore the local config. Global config is global for a reason. But yes, a flag to ignore everything would be nice.
• clarify the real problems this solves; are the benefits sufficient ? The problem is at the very core of command-line interfaces. :) It is painful. Well, at some point there is a limit where the benefits of command line are overtaken by the drawbacks. If it takes me 20 seconds to type a specific command, it is not likely that I will be running it often. Of course, one could create scripts but scripts are also not so easy to modify on the fly and execute. If we copy them, we end up with more scripts than we know what to do with. So, the point is to cut down the repetitive parameters. This saves some time - not so much in terms of absolute time it takes to write the commands but the time from the idea to execution. For example, typing l b since this month is so elegantly convenient compared to ledger -f commodities.ledger -f journal.ledger --price-db ../path/to/my/prices/db/prices.exported.from.gnucash.ledger --price-db ../path/to/my/prices/prices.from.my.price-db.project.ledger --date-format %Y-%m-%d --wide, wait, what was it that I wanted to see, again?!

I could list a few parameters that are good candidates for storing in config files. That might illustrate the benefits easier. Note that I'm still mostly focusing on the local-folder config files. I don't even have the global one cause that moves the parameters way out of sight. (And is more difficult to synchronize between different machines and OS's but that's another matter). I like local configs because I tend to keep related scripts together in the same folder (i.e. time tracking, retirement, cash flow, etc.). I sorted these in the order of priority, as I see it:

• ledger file / book
• price file(s)
• date format
• -X CURRENCY, to show all the reports in the main currency
• date range (i.e. last month/year)

These are the ones I find the most useful so far. The most important is the book file since that appears in literally all the queries we type. Scripts in the local directory also use config file indirectly. If we have, say, 20 scripts / reports and want to apply them to a different book, it is far more convenient to adjust the config file and run them on another book (I use the term book for a ledger file), currency, date range, etc.

A separate question is about the order of parameters. If we supply parameters in the command-line, do they override the ones in the file? Do local files override the global? Or do these append? I would assume they replace as that would be more practical.

[alensiljak]

Added the value proposition to the reply above.

[alensiljak]

Pardon my ignorance, I've just discovered the "Argument files". This, for me, solves the majority of issues from the proposal. It would still be useful to have one more option (.hledgerrc) but is nowhere near as critical. I've created #1027, as I intend to use these very frequently. They seem like a good option for encapsulation of whole reports by listing both the sources, formats, and commands together. I have not (yet) gone through the hledger manual so please take all my suggestions with that in mind and a grain of salt. Thanks again!

[simonmichael]

This has was discussed again recently. https://hledger.org/faq.html#customising documents the current state and workarounds.

We currently don't have a good workaround for https://hledger.org/faq.html#how-can-i-always-run-hledger-with-certain-general-options-.

https://ledger-cli.org/doc/ledger3.html#Environment-variables explains Ledger's ledgerrc config file. Ledger also allows any long flag to be set by environment variables.

If we had a similar file... presumably with a section for general options and a section for each command... it would be up to hledger or each add-on executable to use it or not. Then, unsupported general options there should not be a problem for external add-ons.. but might still be a problem for builtin commands like add. It might be necessary to ensure all builtin commands support all general options, or if that's problematic for the UX (--help), at least support them as hidden flags and ignore them.

[simonmichael]

I've just discovered the "Argument files". This, for me, solves the majority of issues from the proposal. [2019]

@alensiljak , how have argument files worked out for you ?

[simonmichael]

People wanting some kind of config files, would you expect to be able to:

1. add default flags and options (general and command-specific) ?
2. add default arguments (general and command-specific) ?
3. add default journal directives ?
4. use new special directives or other syntax which are specific to config files ? (avoiding the CLI and issues with inconsistent flags support)
5. define custom commands/scripts, as in .gitconfig ?

[simonmichael]

For the record, the general alternative to config files changing hledger's default behaviour is to run hledger directly less, and run custom scripts more. Eg, have a Justfile defining preferred hledger command lines/scripts, in your home directory or specific project directories. https://hledger.org/faq.html#whats-a-good-way-to-manage-hledger-scripts- . A downside of this is it doesn't affect other scripts or tools which run the hledger executable.

[alensiljak]

I have not changed options in years, so these work fine for me so far. In the .ledgerrc file, I set

• main book file (which includes year files)
• price-db path (separate directory)
• date-format
• wide report format

I have not used argument files much since, without lots (or rewriting my whole history in a different way), I can't do much with hledger. One of my main purposes for this type of software is to have things mostly ready when the tax time comes.

[simonmichael]

Thanks @alensiljak.

hledger users wanting config files, we are still short on concrete examples of this feature solving a problem in hledger usage. I mean in full detail, referring to current hledger. Some of the ones I've seen don't seem to hold up when I think about them in practice. Feel free to post (or re-post) yours here.

I have a simple, recent one: current hledger master lets you override -I with -s, so now I'd like to make my hledger enable -I by default. If I make a script as in the faq answer linked above, it breaks commands which don't support -I (hledger test, addons etc.)

[simonmichael]

A related question we should try to answer:

What might be the things hledger users would most often want to customise ? (Globally, or possibly per journal or per individual file, acknowledging that per file usually magnifies complexity)

Eg:

General:

• balance assertion checking
• other correctness checks
• journal file path (currently mostly covered by LEDGER_FILE)
• other data files, to be loaded in addition
• handling of long output (covered by PAGER)
• text editor to run from hledger-ui, hledger-edit etc. (covered by EDITOR)
• colour output (currently covered by COLOR)
• --pretty (unicode box drawing characters)
• --infer-market-prices ?
• --infer-costs / --infer-equity ?
• --auto ?
• --forecast ?
• custom commands/scripts (currently covered by shell aliases/functions, external scripts optionally named hledger-*, makefiles/justfiles)

Command-specific:

• print -x (always print fully explicit entries) ?
• balance commands -S (always show balance reports sorted by amount) ?
• balance commands -l or -t (flat or tree mode) ?
• balance commands --layout ?
• balance commands -N (totals row ?)
• multi-column balance commands -T and -A (row total and row average column) ?

[simonmichael]

From chat:

daveakre:

Speaking for myself, I would get a lot of value from this, in particular:

--infer-market-prices in all commands default time period in all commands default reporting period for bal / bs / is / cf layout configuration in bal / bs / is / cf --tree in bal / bs / is / cf --depth in bal / bs / is / cf --drop in bal / bs / is / cf Today, my workaround is a Justfile But it does mean I need to maintain that separately (and somewhat commingled with other Justfile logic)

[simonmichael]

sm:

a new thought: use environment variables, as (I discovered) ledger does I usually don't love them but for this it would avoid some complexities ie HLEDGER_OPTS, HLEDGER_BALANCE_OPTS, ...

[simonmichael]

Good news everyone. I have pushed some config file support to the conf branch. Any testing will be helpful. You can rename hledger.conf.sample. Here's that file:

# hledger.conf - extra options(/arguments) to be added to hledger commands.
# This takes effect if found in the current directory when you run hledger.

# 1. This first, unnamed section is typically used for general options.
# These affect all commands, or when not supported will be ignored.
# To see the general options available, run hledger -h

# don't check balance assertions by default (run with -s to check them)
--ignore-assertions

# always infer these
--infer-costs
--infer-equity
--infer-market-prices

# always show prettier tables in terminal reports
--pretty


# 2. [named] sections define extra command-specific options.
# Options can be written on the same line or separate lines.
# To see a command's options, run hledger CMD -h

# help: prefer man pages, bypassing info
# [help] --man

# print: show more info by default
[print] --explicit --show-costs

# balance: use these defaults
[balance] --tree -p 'monthly from 3 months ago' --depth 3

# hledger-ui: reload on change (when started via `hledger ui`).
# A -- is needed before addon-specific flags, as on command line.
[ui] -- --watch

--debug (level 1) will show the effect of a config file. --debug=8 will show more details.

[simonmichael]

Config file support has improved, and now has a PR, #2206. Here's the current doc:

Config files

hledger will read extra command line options from a hledger.conf file in the current directory or above, or (named .hledger.conf) in your home directory, or your XDG config directory (~/.config/hledger/).

This config file can contain general options, for use with all commands that support them, and command-specific options for use with particular commands. hledger.conf.sample is an example config file, which you can install as ./hledger.conf or $HOME/.hledger.conf, and customise.

Alternately, you can specify a config file with the --conf option, or you can add a hledger --conf shebang line to a config file and make it executable.

To run without a config file, use the -n/--no-conf flag. This ensures hledger runs with standard defaults, useful when troubleshooting or sharing examples.

You can troubleshoot config file processing with --debug or --debug=8.

and example:

#!/usr/bin/env -S hledger --conf
# hledger.conf - extra options(/arguments) to be added to hledger commands.

# hledger looks for a hledger.conf file in the current directory or above,
# or in your home directory with a dotted name: $HOME/.hledger.conf,
# or in your XDG config directory: $HOME/.config/hledger/hledger.conf.
# You can also execute a conf file with a shebang line like the one above.

# 1. This first, unnamed section is typically used for general options.
# These affect all commands, or when not supported will be ignored.
# To see the general options available, run hledger -h

# don't check balance assertions by default (run with -s to check them)
--ignore-assertions

# always infer these
--infer-costs
--infer-equity
--infer-market-prices

# always show prettier tables in terminal reports
--pretty


# 2. [named] sections define extra command-specific options.
# Options can be written on the same line or separate lines.
# To see a command's options, run hledger CMD -h

# help: prefer man pages, bypassing info
# [help] --man

# print: show more info by default
[print] --explicit --show-costs

# balance commands: use these defaults
[balance]            --tree -p 'monthly from 3 months ago' --depth 3
[balancesheet]       --tree -p 'monthly from 3 months ago' --depth 3
[balancesheetequity] --tree -p 'monthly from 3 months ago' --depth 3
[cashflow]           --tree -p 'monthly from 3 months ago' --depth 3
[incomestatement]    --tree -p 'monthly from 3 months ago' --depth 3

# hledger-ui (when started via `hledger ui`):
# start in Cash accounts screen, limited to depth 3, and watch for changes.
# The -- argument needed on the command line is not needed here.
[ui] --cash -3 --watch

All testing is welcome.

[simonmichael]

This was shipped recently in hledger 1.40, so I'll close this. Testing and feedback is welcome. https://hledger.org/dev/hledger.html#config-files