Repository: borgbackup/borg
Pull request: Doc/4532 faq retain original paths
fixes #4532

Problem statement:
borg backup and btrfs 
This is Fedora 30 Beta and borg is version 1.1.9

When I do a backup of a `btrfs` file system I first do a readonly snapshot, then back up the readonly snapshot.

Example
```
btrfs sub snap -r /home /.snapshots/home
borg create -v -stats /mnt/borg_repos::home.20190428 /.snapshots/home
btrfs sub del /.snapshots/home
```
The problem with this approach is that instead of paths starting with `/home` I have now `/.snapshots/home`.

Anything, I can do here.

Hints from issue discussion:
```
cd /.snapshots
borg create -v -stats /mnt/borg_repos::home.20190428 home
```

alternatively: do it as before and strip away the `.snapshots` at extraction time, see `borg extract --help`.

TODO: check FAQ and docs whether this is already covered. if not, a PR for this is welcome!
`cd /.snapshots` aso is a possible solution for `/home`.

But I have other mount points like for instance: `/data/images` where it doesn't fit nicely. Sure, I could workaround by naming the snapshot: `data.images`.

It would be great to have a mapping parameter in the `borg create` subcommand.
I think I have to deal with it when doing the backup because otherwise the paths look too weird when mounting the repository.
IIRC you can also strip for `borg mount`.
I take this ToDO and make a PR with a new FAQ, mentioning `extract` and `mount` PATH.

Commit message: [DOC] #4532 - More general FAQ for backup and retain original paths

Use correct list syntax.
fixes #4532

Patch to review:
diff --git a/docs/faq.rst b/docs/faq.rst
index 0788c21c52..5c08a5beb8 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -702,6 +702,23 @@ Now Borg will be bandwidth limited. Nice thing about pv is that you can change r
 .. _pipeviewer: http://www.ivarch.com/programs/pv.shtml
 
 
+How can I avoid unwanted base directories getting stored into archives?
+-----------------------------------------------------------------------
+
+Possible use cases:
+
+- Another file system is mounted and you want to backup it with original paths.
+- You have created a BTRFS snapshot in a ``/.snapshots`` directory for backup.
+
+To achieve this, run ``borg_create`` within the mountpoint/snapshot directory:
+
+::
+
+    # Example: Some file system mounted in /mnt/rootfs.
+    cd /mnt/rootfs
+    borg create /path/to/repo::rootfs_backup .
+
+
 I am having troubles with some network/FUSE/special filesystem, why?
 --------------------------------------------------------------------
 


Code review comments:
diff_hunk: @@ -702,6 +702,23 @@ Now Borg will be bandwidth limited. Nice thing about pv is that you can change r
 .. _pipeviewer: http://www.ivarch.com/programs/pv.shtml
 
 
+How can I avoid unwanted base directories getting stored into archives?
+-----------------------------------------------------------------------
+
+Possible use cases:
+
+- Another file system is mounted and you want to backup it with original paths.
+- You have created a BTRFS snapshot in a ``/.snapshots`` directory for backup.
+
+To achieve this, run ``borg_create`` within the mountpoint/snapshot directory:
path: docs/faq.rst
text: @user1:
Hmm, how is this rendered? Is this a link to the borg create docs?

Or should it rather be ```borg create``` (with blank, not underscore)?

@author:
That should be a space, not underscore. Fixed.