use defaults as examples in in borgmatic config generate, or just be (more) consistent #872

New Issue

philsnow · 2024-05-22T19:09:03Z

philsnow commented

2024-05-22 19:09:03 +00:00

What I'd like to do and why

(I'm using 1.8.8 since that's what's available to pkg on freebsd 13.1. I checked open+closed issues, the release notes up to 1.8.11, and the contents of schema.yaml at tip of master, and didn't see anything about this.)

booleans

I just tried borgmatic config generate to get started with a template/skeleton, and the commented-out examples in the output file are sometimes set to the option's default and sometimes set to the opposite:

# Store ctime into archive. Defaults to true.
# ctime: false
[...]
# Record filesystem flags (e.g. NODUMP, IMMUTABLE) in archive.
# Defaults to true.
# flags: true

I would propose that all the examples get set to the defaults (and where the defaults are dependent on the version of borg, use the defaults from more recent versions), because that is what I have seen elsewhere (in particular, in sshd_config(5), where it's explicit that the /etc/ssh/sshd_config that comes packaged contains commented-out defaults, and to make changes you can uncomment and then modify the default).

options that default to not being set

It's less clear what to emit as an example in cases where the default is not set, and certain examples seem to be more useful as examples than their defaults (I'm thinking about ssh_command's default being not-set but the example being ssh -i /path/to/private/key). schema_to_sample_configuration could be amended to emit multiple candidate examples if the schema.yaml example key is an array:

# Command to use instead of "ssh". This can be used to specify ssh
# options. Defaults to not set.
## ssh_command: # default
## ssh_command: ssh -i /path/to/private/key

options that take arrays

If the above change gets made, it could sometimes be ambiguous whether a particular example were a single example or an array of examples, but for options that have schema type array, the code could just detect whether the example was one array or an array-of-arrays (🤢), and if the latter, emit comments something like:

# Exclude directories that contain a file with the given filenames.
# Defaults to not set.
#
## exclude_if_present:  # default
#
## exclude_if_present:
##   - .nobackup
#
## exclude_if_present:
##   - VIDEO_TS
##   - VIDEO_TS.VOB

Whether you think it's worth it to make the latter changes, would you mind a change to schema.yaml that just sets the examples to be the defaults in the trivial cases?

Other notes / implementation ideas

No response

### What I'd like to do and why (I'm using 1.8.8 since that's what's available to `pkg` on freebsd 13.1. I checked open+closed issues, the release notes up to 1.8.11, and the contents of schema.yaml at tip of master, and didn't see anything about this.) ## booleans I just tried `borgmatic config generate` to get started with a template/skeleton, and the commented-out examples in the output file are sometimes set to the option's default and sometimes set to the opposite: ``` # Store ctime into archive. Defaults to true. # ctime: false [...] # Record filesystem flags (e.g. NODUMP, IMMUTABLE) in archive. # Defaults to true. # flags: true ``` I would propose that all the examples get set to the defaults (and where the defaults are dependent on the version of borg, use the defaults from more recent versions), because that is what I have seen elsewhere (in particular, in sshd_config(5), where it's explicit that the /etc/ssh/sshd_config that comes packaged contains commented-out defaults, and to make changes you can uncomment and then modify the default). ## options that default to not being set It's less clear what to emit as an example in cases where the default is not set, and certain examples seem to be more useful _as examples_ than their defaults (I'm thinking about `ssh_command`'s default being not-set but the example being `ssh -i /path/to/private/key`). `schema_to_sample_configuration` could be amended to emit multiple candidate examples if the schema.yaml `example` key is an array: ``` # Command to use instead of "ssh". This can be used to specify ssh # options. Defaults to not set. ## ssh_command: # default ## ssh_command: ssh -i /path/to/private/key ``` ## options that take arrays If the above change gets made, it could sometimes be ambiguous whether a particular example were a single example or an array of examples, but for options that have schema type `array`, the code could just detect whether the example was one array or an array-of-arrays (🤢), and if the latter, emit comments something like: ``` # Exclude directories that contain a file with the given filenames. # Defaults to not set. # ## exclude_if_present: # default # ## exclude_if_present: ## - .nobackup # ## exclude_if_present: ## - VIDEO_TS ## - VIDEO_TS.VOB ``` Whether you think it's worth it to make the latter changes, would you mind a change to schema.yaml that just sets the examples to be the defaults in the trivial cases? ### Other notes / implementation ideas _No response_

witten commented

2024-06-04 18:06:35 +00:00

Thanks for taking the time to file this!

I just tried borgmatic config generate to get started with a template/skeleton, and the commented-out examples in the output file are sometimes set to the option's default and sometimes set to the opposite:

The original intention with most of the examples being a non-default value is to serve as a more realistic illustration of what you might want to set an option's value to. In other words, you're never going to set an option to its default (presumably), so let's show you what a non-default value looks like!

Having said that, I'm not wedded to this approach.

Whether you think it's worth it to make the latter changes, would you mind a change to schema.yaml that just sets the examples to be the defaults in the trivial cases?

I'd be fine with that for the simple cases, but I do think as you've pointed out there are some cases where examples are actually useful. So I think the way to support that easily would be just to make example: optional in the borgmatic schema; manually omit it for the simple cases and then if an example is actually useful, include it in the schema and make use of it when generating the config.

As for emitting multiple candidate examples, I'd also be fine with that as well, but I don't think it's absolutely necessary for this general scheme to work.

Thanks for taking the time to file this! > I just tried borgmatic config generate to get started with a template/skeleton, and the commented-out examples in the output file are sometimes set to the option's default and sometimes set to the opposite: The original intention with most of the examples being a non-default value is to serve as a more realistic illustration of what you might want to set an option's value to. In other words, you're never going to set an option to its default (presumably), so let's show you what a non-default value looks like! Having said that, I'm not wedded to this approach. > Whether you think it's worth it to make the latter changes, would you mind a change to schema.yaml that just sets the examples to be the defaults in the trivial cases? I'd be fine with that for the simple cases, but I do think as you've pointed out there are some cases where examples are actually useful. So I think the way to support that easily would be just to make `example:` optional in the borgmatic schema; manually omit it for the simple cases and then if an example is actually useful, include it in the schema and make use of it when generating the config. As for emitting multiple candidate examples, I'd also be fine with that as well, but I don't think it's absolutely necessary for this general scheme to work.

Sign in to join this conversation.