doc/bugs/content_retrieval_from_borg_remote_fails_over_ssh.mdwn

@@ -0,0 +1,73 @@
+### Please describe the problem.
+
+The borg special remote is awesome and works perfectly if the borg repo is local. However, fetching content (e.g., with `git annex get` or `git annex sync --content`) seems to fail if the borg repo is accessed over ssh.
+
+### What steps will reproduce the problem?
+
+On remote host:
+
+[[!format sh """
+# Init borg repo
+borg init --encryption=none /home/remote_user/borg_repo
+"""]]
+
+On local host:
+
+[[!format sh """
+# Set environment variable for clarity
+export BORG_REPO=remote_user@remote_host:/home/remote_user/borg_repo
+
+# Init git-annex repo on local host and add borg repo as semitrusted remote
+git init git_repo && cd git_repo
+git annex init git_repo
+git annex initremote borg type=borg borgrepo=$BORG_REPO appendonly=yes
+
+# Commit content to git-annex, create borg archive, and sync
+echo content > file.txt
+git annex add file.txt
+git commit -m init
+borg create $BORG_REPO::archive_name .
+git annex sync borg
+
+# Drop content from git-annex
+git annex drop file.txt
+
+# NOTE: Up to this point, everything is fine.
+
+# Now, attempt to retrieve content from borg
+git annex get file.txt
+"""]]
+
+The final step results in error. Please see the output below in the additional information section.
+
+### What version of git-annex are you using? On what operating system?
+
+- git-annex version: 8.20210428
+- operation system: linux x86_64 (NixOS 21.05)
+
+(NOTE: This was also tested on an old macOS machine with the same results.)
+
+### Please provide any additional information below.
+
+The following output shows an apparent concatenation of the local git-annex repo path with the remote borg repo path:
+
+[[!format sh """
+$ git annex get file.txt
+get file.txt (from borg...)
+Repository /home/local_user/git_repo/remote_user@remote_host:/home/remote_user/borg_repo does not exist.
+
+  user error (borg ["extract","/home/local_user/git_repo/remote_user@remote_host:/home/remote_user/borg_repo::archive_name",".git/annex/objects/QV/p6/SHA256E-s8--12a61f4e173fb3a11c05d6471f74728f76231b4a5fcd9667cef3af87a3ae4dc3.txt/SHA256E-s8--12a61f4e173fb3a11c05d6471f74728f76231b4a5fcd9667cef3af87a3ae4dc3.txt"] exited 2)
+
+  Unable to access these remotes: borg
+
+  No other repository is known to contain the file.
+failed
+get: 1 failed
+exit 1
+"""]]
+
+NOTE: I tried several variations of the ssh url syntax, but they all resulted in the same error.
+
+### Have you had any luck using git-annex before? (Sometimes we get tired of reading bug reports all day and a lil' positive end note does wonders)
+
+Definitely. I love git-annex. I LOVE it. It has no equal and is the secret to my productivity, not to mention peace of mind in this epoch. Much, much respect.