docs: add warning about prune

docs/quickstart.rst

@@ -85,9 +85,12 @@ certain number of old archives::
         --exclude /home/Ben/Music/Justin\ Bieber    \
         --exclude '*.pyc'
 
-    # Use the `prune` subcommand to maintain 7 daily, 4 weekly
+    # Use the `prune` subcommand to maintain 7 daily, 4 weekly and 6 monthly
-    # and 6 monthly archives.
+    # archives of THIS machine. --prefix `hostname`- is very important to
-    borg prune -v $REPOSITORY --keep-daily=7 --keep-weekly=4 --keep-monthly=6
+    # limit prune's operation to this machine's archives and not apply to
+    # other machine's archives also.
+    borg prune -v $REPOSITORY --prefix `hostname`- \
+        --keep-daily=7 --keep-weekly=4 --keep-monthly=6
 
 .. backup_compression:
 

docs/usage.rst

@@ -265,10 +265,23 @@ Examples
 
 Examples
 ~~~~~~~~
+
+Be careful, prune is potentially dangerous command, it will remove backup
+archives.
+
+The default of prune is to apply to **all archives in the repository** unless
+you restrict its operation to a subset of the archives using `--prefix`.
+When using --prefix, be careful to choose a good prefix - e.g. do not use a
+prefix "foo" if you do not also want to match "foobar".
+
+It is strongly recommended to always run `prune --dry-run ...` first so you
+will see what it would do without it actually doing anything.
+
 ::
 
-    # Keep 7 end of day and 4 additional end of week archives:
+    # Keep 7 end of day and 4 additional end of week archives.
-    $ borg prune /mnt/backup --keep-daily=7 --keep-weekly=4
+    # Do a dry-run without actually deleting anything.
+    $ borg prune /mnt/backup --dry-run --keep-daily=7 --keep-weekly=4
 
     # Same as above but only apply to archive names starting with "foo":
     $ borg prune /mnt/backup --keep-daily=7 --keep-weekly=4 --prefix=foo