From 26071de2e766d2eec278761c6d382fd5abec9dc3 Mon Sep 17 00:00:00 2001
From: Dan Helfman <witten@torsion.org>
Date: Mon, 18 Feb 2019 22:43:32 -0800
Subject: [PATCH] Update extraction docs.

---
 NEWS                            |  6 ++--
 README.md                       |  1 +
 docs/how-to/restore-a-backup.md | 61 +++++++++++++++++++++++++++++++++
 setup.py                        |  2 +-
 4 files changed, 66 insertions(+), 4 deletions(-)
 create mode 100644 docs/how-to/restore-a-backup.md

diff --git a/NEWS b/NEWS
index f08d88ca..b6217d51 100644
--- a/NEWS
+++ b/NEWS
@@ -1,9 +1,9 @@
-1.2.16.dev0
+1.2.16
+ * #119: Include a sample borgmatic configuration file in the documentation.
+ * #123: Support for Borg archive restoration via borgmatic --extract command-line flag.
  * Refactor documentation into multiple separate pages for clarity and findability.
  * Organize options within command-line help into logical groups.
  * Exclude tests from distribution packages.
- * #119: Include a sample borgmatic configuration file in the documentation.
- * #123: Support for Borg archive restoration via borgmatic --extract command-line flag.
 
 1.2.15
  * #127: Remove date echo from schema example, as it's not a substitute for real logging.
diff --git a/README.md b/README.md
index f9ec0617..50ef9d47 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,7 @@ href="https://asciinema.org/a/203761" target="_blank">screencast</a>.
  * [Make per-application backups](docs/how-to/make-per-application-backups.md)
  * [Deal with very large backups](docs/how-to/deal-with-very-large-backups.md)
  * [Inspect your backups](docs/how-to/inspect-your-backups.md)
+ * [Restore a backup](docs/how-to/restore-a-backup.md)
  * [Run preparation steps before backups](docs/how-to/run-preparation-steps-before-backups.md)
  * [Upgrade borgmatic](docs/how-to/upgrade.md)
  * [Develop on borgmatic](docs/how-to/develop-on-borgmatic.md)
diff --git a/docs/how-to/restore-a-backup.md b/docs/how-to/restore-a-backup.md
new file mode 100644
index 00000000..e8b21965
--- /dev/null
+++ b/docs/how-to/restore-a-backup.md
@@ -0,0 +1,61 @@
+---
+title: How to restore a backup
+---
+## Extract
+
+When the worst happens—or you want to test your backups—the first step is
+to figure out which archive to restore. A good way to do that is to use the
+`--list` action:
+
+```bash
+borgmatic --list
+```
+
+That should yield output looking something like:
+
+```text
+host-2019-01-01T04:05:06.070809      Tue, 2019-01-01 04:05:06 [...]
+host-2019-01-02T04:06:07.080910      Wed, 2019-01-02 04:06:07 [...]
+```
+
+Assuming that you want to restore the archive with the most up-to-date files
+and therefore the latest timestamp, run a command like:
+
+```bash
+borgmatic --extract --archive host-2019-01-02T04:06:07.080910
+```
+
+The `--archive` value is the name of the archive to restore. This extracts the
+entire contents of the archive to the current directory, so make sure you're
+in the right place before running the command.
+
+
+## Repository selection
+
+If you have a single repository in your borgmatic configuration file(s), no
+problem: the `--extract` action figures out which repository to use.
+
+But if you have multiple repositories configured, then you'll need to specify
+the repository path containing the archive to extract. Here's an example:
+
+```bash
+borgmatic --extract --repository repo.borg --archive host-2019-...
+```
+
+## Restore particular files
+
+Sometimes, you want to restore a single deleted file, rather than restoring
+everything from an archive. To do that, tack on one or more `--restore-path`
+values. For instance:
+
+```bash
+borgmatic --extract --archive host-2019-... --restore-path /path/1 /path/2
+```
+
+Like a whole-archive restore, this also restores into the current directory.
+
+
+## Related documentation
+
+ * [Set up backups with borgmatic](../../docs/how-to/set-up-backups.md)
+ * [Inspect your backups](../../docs/how-to/inspect-your-backups.md)
diff --git a/setup.py b/setup.py
index 5a76fd19..4770151c 100644
--- a/setup.py
+++ b/setup.py
@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 
-VERSION = '1.2.16.dev0'
+VERSION = '1.2.16'
 
 
 setup(