Clarify required versus optional config values #57

New Issue

witten · 2018-02-18T22:09:11Z

witten commented

2018-02-18 22:09:11 +00:00

When running generate-borgmatic-config, the command generates a giant config file full of both optional and required configuration values. But only two of the values are actually required, and it's not the best first-time user experience to have to wade through most of the values just to end up deleting them or commenting them out.

So as part of this ticket, improve that first-time experience and make it more obvious which values are required.

Implementation ideas

Idea 1:

Make it more explicit in the generated config file comments:

   # VALUE: source_directories:
   # DEFAULT: /etc
   # [REQUIRED] List of source directories to backup. Globs and tildes are expanded.
   source_directories:
        - /etc
        - /var/www/
        - /var/log/
        - /home/user/data files

(Idea from Zach Coffey.)

Idea 2:

Generate the example config file with optional values commented out, so it's clear that you really just need to focus on the commented-in required values.

Idea 3:

Add a flag to generate-borgmatic-config that generates just the minimal config file with only the required values set.

When running `generate-borgmatic-config`, the command generates a giant config file full of both optional and required configuration values. But only two of the values are actually required, and it's not the best first-time user experience to have to wade through most of the values just to end up deleting them or commenting them out. So as part of this ticket, improve that first-time experience and make it more obvious which values are required. **Implementation ideas** Idea 1: Make it more explicit in the generated config file comments: ``` # VALUE: source_directories: # DEFAULT: /etc # [REQUIRED] List of source directories to backup. Globs and tildes are expanded. source_directories: - /etc - /var/www/ - /var/log/ - /home/user/data files ``` (Idea from Zach Coffey.) Idea 2: Generate the example config file with optional values commented out, so it's clear that you really just need to focus on the commented-in required values. Idea 3: Add a flag to `generate-borgmatic-config` that generates just the minimal config file with only the required values set.

witten referenced this issue from a commit

2018-09-29 22:08:12 +00:00

In generate-borgmatic-config, comment out all optional config (#57).

witten commented

2018-09-29 22:10:21 +00:00

Implemented idea 2 (optional values render as commented out) in borgmatic 1.2.5.

witten closed this issue

2018-09-29 22:10:21 +00:00

witten referenced this issue from a commit

2023-03-27 22:55:26 +00:00

Labels for repositories (#635).

Sign in to join this conversation.