From 795d9abad28739fe87eceaa7ae996ef6d1a487c6 Mon Sep 17 00:00:00 2001
From: remyabel <70660631+remyabel@users.noreply.github.com>
Date: Wed, 25 Aug 2021 15:42:07 -0400
Subject: [PATCH] docs: clarify user_id vs uid for fuse (#5958)

docs: clarify user_id vs uid for fuse, fixes #5723
---
 src/borg/archiver.py | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/src/borg/archiver.py b/src/borg/archiver.py
index d1da6533b..a2fae16d9 100644
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -2918,6 +2918,23 @@ def define_borg_mount(parser):
 
         For FUSE configuration and mount options, see the mount.fuse(8) manual page.
 
+        Borg's default behavior is to use the archived user and group names of each
+        file and map them to the system's respective user and group ids.
+        Alternatively, using ``numeric-ids`` will instead use the archived user and
+        group ids without any mapping.
+
+        The ``uid`` and ``gid`` mount options (implemented by Borg) can be used to
+        override the user and group ids of all files (i.e., ``borg mount -o
+        uid=1000,gid=1000``).
+
+        The man page references ``user_id`` and ``group_id`` mount options
+        (implemented by fuse) which specify the user and group id of the mount owner
+        (aka, the user who does the mounting). It is set automatically by libfuse (or
+        the filesystem if libfuse is not used). However, you should not specify these
+        manually. Unlike the ``uid`` and ``gid`` mount options which affect all files,
+        ``user_id`` and ``group_id`` affect the user and group id of the mounted
+        (base) directory.
+
         Additional mount options supported by borg:
 
         - versions: when used with a repository mount, this gives a merged, versioned