From e74110a833d65743c927d21cac6bd84c503163a3 Mon Sep 17 00:00:00 2001
From: Quentin Lemaire <quentin@lemairepro.fr>
Date: Mon, 13 Apr 2020 04:39:50 +0200
Subject: [PATCH] docs: Write new entry to changelog/unreleased

---
 changelog/unreleased/issue-2688 | 26 ++++++++++++++++++++++++++
 doc/manual_rest.rst             |  2 +-
 2 files changed, 27 insertions(+), 1 deletion(-)
 create mode 100644 changelog/unreleased/issue-2688

diff --git a/changelog/unreleased/issue-2688 b/changelog/unreleased/issue-2688
new file mode 100644
index 000000000..2f6532f57
--- /dev/null
+++ b/changelog/unreleased/issue-2688
@@ -0,0 +1,26 @@
+Bugfix: Make backup and tag commands separate tags by comma
+
+Running `restic backup --tag foo,bar` previously created snapshots with one
+single tag containing a comma ("foo,bar") instead of two tags ("foo", "bar").
+Similarly, the `tag` command's --set, --add and --remove options would treat
+"foo,bar" as one tag instead of two tags. This was inconsistent with other
+commands and often unexpected when one intended "foo,bar" to mean two tags.
+
+To be consistent in all commands, restic now interprets "foo,bar" to mean two
+separate tags ("foo" and "bar") instead of one tag ("foo,bar") everywhere,
+including in the `backup` and `tag` commands.
+
+NOTE: This change might result in unexpected behavior in cases where you use
+the `forget` command and filter on tags like "foo,bar". Snapshots previously
+backed up with `--tag foo,bar` will still not match that filter, but snapshots
+saved from now on will match that filter.
+
+To replace "foo,bar" tags with "foo" and "bar" tags in old snapshots, you can
+first generate a list of the relevant snapshots using a command like
+`restic snapshots --json --quiet | jq '.[] | select(contains({tags: ["foo,bar"]})) | .id'`
+, and then use `restic tag --set foo --set bar snapshotID [...]` to set the new
+tags. Please adjust the commands to real tag names and any additional tags,
+as well as the list of snapshots to process.
+
+https://github.com/restic/restic/issues/2688
+https://github.com/restic/restic/pull/2690
diff --git a/doc/manual_rest.rst b/doc/manual_rest.rst
index f84663eab..9b2f9f194 100644
--- a/doc/manual_rest.rst
+++ b/doc/manual_rest.rst
@@ -105,7 +105,7 @@ command:
           --parent snapshot                        use this parent snapshot (default: last snapshot in the repo that has the same target files/directories)
           --stdin                                  read backup from stdin
           --stdin-filename filename                filename to use when reading from stdin (default "stdin")
-          --tag tag                                add a tag for the new snapshot (can be specified multiple times)
+          --tag tag                                add `tags` for the new snapshot in the format `tag[,tag,...]` (can be specified multiple times)
           --time time                              time of the backup (ex. '2012-11-01 22:08:41') (default: now)
           --use-fs-snapshot                        use filesystem snapshot where possible (currently only Windows VSS)
           --with-atime                             store the atime for all files and directories