From be15a9261ad101949eb93d68d18c51fcee55ef03 Mon Sep 17 00:00:00 2001
From: Pauline Middelink <middelin@google.com>
Date: Sun, 5 Mar 2017 19:06:06 +0100
Subject: [PATCH] Add design and user documentation for the `restic tag`
 command

---
 doc/Design.md | 16 +++++++++++++---
 doc/Manual.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 3 deletions(-)

diff --git a/doc/Design.md b/doc/Design.md
index 117554d2b..e244245a2 100644
--- a/doc/Design.md
+++ b/doc/Design.md
@@ -285,7 +285,7 @@ This way, the password can be changed without having to re-encrypt all data.
 Snapshots
 ---------
 
-A snapshots represents a directory with all files and sub-directories at a
+A snapshot represents a directory with all files and sub-directories at a
 given point in time. For each backup that is made, a new snapshot is created. A
 snapshot is a JSON document that is stored in an encrypted file below the
 directory `snapshots` in the repository. The filename is the storage ID. This
@@ -304,12 +304,22 @@ enter password for repository:
   "hostname": "kasimir",
   "username": "fd0",
   "uid": 1000,
-  "gid": 100
+  "gid": 100,
+  "tags": [
+    "NL"
+  ],
+  "original": "251c2e5841355f743f9d4ffd3260bee765acee40a6229857e32b60446991b837"
 }
 ```
 
 Here it can be seen that this snapshot represents the contents of the directory
-`/tmp/testdata`. The most important field is `tree`.
+`/tmp/testdata` after its tags were changed to "NL". The most important field
+is `tree`.
+
+Another important field is `original`, if any modification is made to the
+snapshot, say because its tags changed, its SHA-256 hash changes and therefore
+the original snapshot id is lost. Retaining a stable id is especially important
+for caching.
 
 All content within a restic repository is referenced according to its SHA-256
 hash. Before saving, each file is split into variable sized Blobs of data. The
diff --git a/doc/Manual.md b/doc/Manual.md
index 3612b6f0e..fe52735d9 100644
--- a/doc/Manual.md
+++ b/doc/Manual.md
@@ -73,6 +73,7 @@ Available Commands:
   rebuild-index build a new index file
   restore       extract the data from a snapshot
   snapshots     list all snapshots
+  tag           modifies tags on snapshots
   unlock        remove locks other processes created
   version       Print version information
 
@@ -394,6 +395,34 @@ enter password for repository:
 *eb78040b    username    kasimir   2015-08-12 13:29:57
 ```
 
+# Manage tags
+
+Managing tags on snapshots is simple. The existing set of tags can be either
+replaced completely, added to or removed from. The result is directly visible
+in the `snapshots` command.
+
+```console
+$ restic -r /tmp/backup tag --set NL,CH 590c8fc8
+Create exclusive lock for repository
+Modified tags on 1 snapshots
+```
+Note the snapshot ID has changed, so between each change we need to look up
+the new ID of the snapshot. But there is an even better way, the `tag` command
+accepts `--tag`, so we can filter snapshots based on the tag we just added.
+```console
+$ restic -r /tmp/backup tag --tag NL --remove CH
+Create exclusive lock for repository
+Modified tags on 1 snapshots
+$ restic -r /tmp/backup tag --tag NL --add UK
+Create exclusive lock for repository
+Modified tags on 1 snapshots
+$ restic -r /tmp/backup tag --tag NL --remove NL
+Create exclusive lock for repository
+Modified tags on 1 snapshots
+$ restic -r /tmp/backup tag --tag NL --add SOMETHING
+No snapshots were modified
+```
+
 # Check integrity and consistency
 
 Imagine your repository is saved on a server that has a faulty hard drive, or