From 95a0bd7422703985f1e97e6433cf619f9522f3a6 Mon Sep 17 00:00:00 2001
From: Barrett Ruth <br.barrettruth@gmail.com>
Date: Mon, 16 Mar 2026 14:25:21 -0400
Subject: [PATCH] docs(ssh): expand SSH adapter documentation (#525)

Problem: the `:help oil-adapter-ssh` section was only 10 lines covering
URL format and server requirements. Users had no guidance on how the
adapter works, how to configure `extra_scp_args`, or how to troubleshoot
connection issues.

Solution: expand the section with architecture overview (persistent SSH
connection, `scp` for file transfer, no local mount), configuration
(`extra_scp_args`, `~/.ssh/config`), limitations (no third-party plugin
integration, no cross-adapter moves), and troubleshooting tips.
---
 doc/oil.txt     | 50 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/upstream.md |  2 +-
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/doc/oil.txt b/doc/oil.txt
index be7ea73..74a92ba 100644
--- a/doc/oil.txt
+++ b/doc/oil.txt
@@ -916,6 +916,56 @@ SSH                                                              *oil-adapter-ss
     server to have `/bin/sh` as well as standard unix commands (`ls`, `rm`,
     `mv`, `mkdir`, `chmod`, `cp`, `touch`, `ln`, `echo`).
 
+    How it works ~
+
+    Oil opens a persistent SSH connection to the remote host and runs shell
+    commands over stdin/stdout. Nothing is mounted locally. Directory listings
+    come from `ls -la`; file reads and writes go through `scp`. One connection
+    is maintained per unique host/port/user combination and reused across
+    buffers.
+
+    If the connection takes longer than 2 seconds (e.g. waiting for a password
+    or host-key confirmation), oil automatically opens a floating terminal so
+    you can interact with the SSH prompt. Configure this window with the `ssh`
+    key in `float_win_config`: >lua
+        require("oil").setup({
+          float_win_config = {
+            ssh = { border = "rounded" },
+          },
+        })
+<
+    Configuration ~
+
+    Pass extra flags to `scp` with `extra_scp_args`. This is useful for hosts
+    that require legacy SCP protocol (`-O`) or a specific cipher: >lua
+        require("oil").setup({
+          extra_scp_args = { "-O" },
+        })
+<
+    The underlying `ssh` command respects `~/.ssh/config`, so per-host
+    settings like `IdentityFile`, `ProxyJump`, and `Port` work as expected.
+
+    Limitations ~
+
+    The SSH adapter is self-contained. It does not expose a mount point or
+    local filesystem path, so other plugins (Telescope, tree views, LSP)
+    cannot access remote files through it. For full remote development,
+    consider mounting the remote filesystem with `sshfs` or using
+    `distant.nvim`.
+
+    Files can be copied between local and SSH adapters (uses `scp`), but
+    cross-adapter moves are not supported — use copy + delete instead.
+
+    Troubleshooting ~
+
+    Connection hangs: Check that key-based authentication is configured in
+    `~/.ssh/config`. Password prompts work but require interaction through
+    the floating terminal.
+
+    Permission denied on `scp`: Some hosts (notably Synology NAS) expose a
+    different directory tree over SFTP than over SSH. Try adding `-O` to
+    `extra_scp_args` to force the legacy SCP protocol.
+
 S3                                                                *oil-adapter-s3*
 
     Browse files stored in AWS S3. Make sure `aws` is configured correctly,
diff --git a/doc/upstream.md b/doc/upstream.md
index e81c7ec..1f73f63 100644
--- a/doc/upstream.md
+++ b/doc/upstream.md
@@ -91,7 +91,7 @@ issues against this fork.
 | [#492](https://github.com/stevearc/oil.nvim/issues/492) | j/k remapping question                                     | not actionable — answered                                                                                                                                 |
 | [#507](https://github.com/stevearc/oil.nvim/issues/507) | lacasitos.nvim conflict                                    | not actionable — cross-plugin + Windows-only                                                                                                              |
 | [#521](https://github.com/stevearc/oil.nvim/issues/521) | oil-ssh connection issues                                  | open                                                                                                                                                      |
-| [#525](https://github.com/stevearc/oil.nvim/issues/525) | SSH adapter documentation                                  | open                                                                                                                                                      |
+| [#525](https://github.com/stevearc/oil.nvim/issues/525) | SSH adapter documentation                                  | fixed — expanded `:help oil-adapter-ssh`                                                                                                                  |
 | [#531](https://github.com/stevearc/oil.nvim/issues/531) | Incomplete drive letters                                   | not actionable — Windows-only                                                                                                                             |
 | [#533](https://github.com/stevearc/oil.nvim/issues/533) | `constrain_cursor` bug                                     | not actionable — needs repro                                                                                                                              |
 | [#570](https://github.com/stevearc/oil.nvim/issues/570) | Improve c0/d0 for renaming                                 | not actionable — blocked on Neovim extmark API                                                                                                            |