archiver: warn about MSYS2 path translation, fixes #9339

This adds a runtime warning when running under MSYS2/Git Bash without the necessary environment variables to disable automatic path translation. The documentation is also updated to explain this behavior and how to mitigate it.

Author: trxvorr

docs/installation.rst

@@ -328,6 +328,29 @@ Install the dependencies with the provided script::
 
     ./scripts/msys2-install-deps
 
+.. _msys2_path_translation:
+
+MSYS2 Path Translation
+++++++++++++++++++++++
+
+When running Borg within an MSYS2 (including Git Bash) environment, the shell
+automatically translates POSIX-style paths (like ``/tmp`` or ``/c/Users``) to
+Windows paths (like ``C:\msys64\tmp`` or ``C:\Users``) before they reach the
+Borg process.
+
+This behavior can result in absolute Windows paths being stored in your backups,
+which may not be what you intended if you use POSIX paths for portability.
+
+To disable this automatic translation for Borg, you can use environment variables
+to exclude everything from conversion. Similarly, MSYS2 also translates
+environment variables that look like paths. To disable this generally for Borg,
+set both variables::
+
+    export MSYS2_ARG_CONV_EXCL="*"
+    export MSYS2_ENV_CONV_EXCL="*"
+
+For more details, see the `MSYS2 documentation on filesystem paths <https://www.msys2.org/docs/filesystem-paths/>`__.
+
 Windows 10's Linux Subsystem
 ++++++++++++++++++++++++++++
 

src/borg/archiver/__init__.py

@@ -455,7 +455,14 @@ def parse_args(self, args=None):
         return args
 
     def prerun_checks(self, logger, is_serve):
-
+        if not is_serve:
+            if sys.platform == "win32" and "MSYSTEM" in os.environ:
+                if "MSYS2_ARG_CONV_EXCL" not in os.environ or "MSYS2_ENV_CONV_EXCL" not in os.environ:
+                    logger.warning(
+                        "MSYS2 path translation is active. This can cause POSIX paths to be mangled into "
+                        "Windows paths in archives. Consider setting MSYS2_ARG_CONV_EXCL='*' and "
+                        "MSYS2_ENV_CONV_EXCL='*'. See https://www.msys2.org/docs/filesystem-paths/ for details."
+                    )
         selftest(logger)
 
     def _setup_implied_logging(self, args):