Documentation updates based on the new YAML configuration.

README.md

@@ -24,6 +24,10 @@ location:
     # Path to local or remote repository.
     repository: user@backupserver:sourcehostname.borg
 
+    # Any paths matching these patterns are excluded from backups.
+    exclude_patterns:
+        - /home/*/.cache
+
 retention:
     # Retention policy for how many backups to keep in each category.
     keep_daily: 7
@@ -37,16 +41,13 @@ consistency:
         - archives
 ```
 
-Additionally, exclude patterns can be specified in a separate excludes config
-file, one pattern per line.
-
 borgmatic is hosted at <https://torsion.org/borgmatic> with [source code
 available](https://torsion.org/hg/borgmatic). It's also mirrored on
 [GitHub](https://github.com/witten/borgmatic) and
 [BitBucket](https://bitbucket.org/dhelfman/borgmatic) for convenience.
 
 
-## Setup
+## Installation
 
 To get up and running, follow the [Borg Quick
 Start](https://borgbackup.readthedocs.org/en/latest/quickstart.html) to create
@@ -66,19 +67,45 @@ To install borgmatic, run the following command to download and install it:
 Make sure you're using Python 3, as borgmatic does not support Python 2. (You
 may have to use "pip3" instead of "pip".)
 
-Then, download a [sample config
+Then, generate a sample configuration file:
-file](https://torsion.org/hg/borgmatic/raw-file/tip/sample/config.yaml) and a
-[sample excludes
-file](https://torsion.org/hg/borgmatic/raw-file/tip/sample/excludes). From the
-directory where you downloaded them:
 
-    sudo mkdir /etc/borgmatic/
+    sudo generate-borgmatic-config
-    sudo mv config.yaml excludes /etc/borgmatic/
 
-Lastly, modify the /etc files with your desired configuration.
+This generates a sample configuration file at /etc/borgmatic/config.yaml (by
+default). You should edit the file to suit your needs, as the values are just
+representative. All fields are optional except where indicated, so feel free
+to remove anything you don't need.
 
 
-## Upgrading from atticmatic
+## Upgrading
+
+In general, all you should need to do to upgrade borgmatic is run the
+following:
+
+    sudo pip install --upgrade borgmatic
+
+However, see below about special cases.
+
+### Upgrading from borgmatic 1.0.x
+
+borgmatic changed its configuration file format in version 1.1.0 from
+INI-style to YAML. This better supports validation, and has a more natural way
+to express lists of values. To upgrade your existing configuration, first
+upgrade to the new version of borgmatic:
+
+    sudo pip install --upgrade borgmatic
+
+Then, run:
+
+    sudo upgrade-borgmatic-configuration
+
+That will generate a new YAML configuration file at /etc/borgmatic/config.yaml
+(by default) using the values from both your existing configuration and
+excludes files. The new version of borgmatic will consume the YAML
+configuration file instead of the old one.
+
+
+### Upgrading from atticmatic
 
 You can ignore this section if you're not an atticmatic user (the former name
 of borgmatic).
@@ -98,6 +125,7 @@ from atticmatic to borgmatic. Simply run the following commands:
 That's it! borgmatic will continue using your /etc/borgmatic configuration
 files.
 
+
 ## Usage
 
 You can run borgmatic and start a backup simply by invoking it without

borgmatic/commands/generate_config.py

@@ -34,6 +34,11 @@ def main():  # pragma: no cover
         args = parse_arguments(*sys.argv[1:])
 
         generate.generate_sample_configuration(args.destination_filename, validate.schema_filename())
+
+        print('Generated a sample configuration file at {}.'.format(args.destination_filename))
+        print()
+        print('Please edit the file to suit your needs. The values are just representative.')
+        print('All fields are optional except where indicated.')
     except (ValueError, OSError) as error:
         print(error, file=sys.stderr)
         sys.exit(1)

borgmatic/config/schema.yaml

@@ -12,7 +12,7 @@ map:
                 required: True
                 seq:
                     - type: scalar
-                desc: List of source directories to backup. Globs are expanded.
+                desc: List of source directories to backup (required). Globs are expanded.
                 example:
                     - /home
                     - /etc
@@ -28,16 +28,15 @@ map:
             repository:
                 required: True
                 type: scalar
-                desc: Path to local or remote repository.
+                desc: Path to local or remote repository (required).
                 example: user@backupserver:sourcehostname.borg
             exclude_patterns:
                 seq:
                     - type: scalar
                 desc: |
-                    Exclude patterns. Any paths matching these patterns are excluded from backups.
+                    Any paths matching these patterns are excluded from backups. Globs are expanded.
-                    Globs are expanded. See
+                    See https://borgbackup.readthedocs.io/en/stable/usage.html#borg-help-patterns
-                    https://borgbackup.readthedocs.io/en/stable/usage.html#borg-help-patterns for
+                    for details.
-                    details.
                 example:
                     - '*.pyc'
                     - /home/*/.cache

sample/config

@@ -1,48 +0,0 @@
-[location]
-# Space-separated list of source directories to backup.
-# Globs are expanded.
-source_directories: /home /etc /var/log/syslog*
-
-# Stay in same file system (do not cross mount points).
-#one_file_system: True
-
-# Alternate Borg remote executable (defaults to "borg"):
-#remote_path: borg1
-
-# Path to local or remote repository.
-repository: user@backupserver:sourcehostname.borg
-
-[storage]
-# Passphrase to unlock the encryption key with. Only use on repositories that
-# were initialized with passphrase/repokey encryption.
-#encryption_passphrase: foo
-
-# Type of compression to use when creating archives. See
-# https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create
-# for details. Defaults to no compression.
-#compression: lz4
-
-# Umask to be used for borg create.
-#umask: 0077
-
-[retention]
-# Retention policy for how many backups to keep in each category. See
-# https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
-#keep_within: 3H
-#keep_hourly: 24
-keep_daily: 7
-keep_weekly: 4
-keep_monthly: 6
-keep_yearly: 1
-
-#prefix: sourcehostname
-
-[consistency]
-# Space-separated list of consistency checks to run: "repository", "archives",
-# or both. Defaults to both. Set to "disabled" to disable all consistency
-# checks. See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check
-# for details.
-checks: repository archives
-
-# Restrict the number of checked archives to the last n.
-#check_last: 3

sample/config.yaml

@@ -1,56 +0,0 @@
-location:
-    # List of source directories to backup. Globs are expanded.
-    source_directories:
-        - /home
-        - /etc
-        - /var/log/syslog*
-
-    # Stay in same file system (do not cross mount points).
-    #one_file_system: yes
-
-    # Alternate Borg remote executable (defaults to "borg"):
-    #remote_path: borg1
-
-    # Path to local or remote repository.
-    repository: user@backupserver:sourcehostname.borg
-
-#storage:
-    # Passphrase to unlock the encryption key with. Only use on repositories
-    # that were initialized with passphrase/repokey encryption. Quote the value
-    # if it contains punctuation so it parses correctly. And backslash any
-    # quote or backslash literals as well.
-    #encryption_passphrase: "foo"
-
-    # Type of compression to use when creating archives. See
-    # https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create
-    # for details. Defaults to no compression.
-    #compression: lz4
-
-    # Umask to be used for borg create.
-    #umask: 0077
-
-retention:
-    # Retention policy for how many backups to keep in each category. See
-    # https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for
-    # details.
-    #keep_within: 3H
-    #keep_hourly: 24
-    keep_daily: 7
-    keep_weekly: 4
-    keep_monthly: 6
-    keep_yearly: 1
-
-    # When pruning, only consider archive names starting with this prefix.
-    #prefix: sourcehostname
-
-consistency:
-    # List of consistency checks to run: "repository", "archives", or both.
-    # Defaults to both. Set to "disabled" to disable all consistency checks.
-    # See https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check
-    # for details.
-    checks:
-        - repository
-        - archives
-
-    # Restrict the number of checked archives to the last n.
-    #check_last: 3

sample/excludes

@@ -1,3 +0,0 @@
-*.pyc
-/home/*/.cache
-/etc/ssl