barrett/canola.nvim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3

docs(ssh): expand SSH adapter documentation (#525) (#138)

Browse source 
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.
This commit is contained in:
Barrett Ruth 2026-03-16 14:29:20 -04:00 • committed by GitHub
parent 7372c98e2b
commit 136c11db71
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 51 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

50
doc/oil.txt
View file

@ -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,

2
doc/upstream.md
View file

@ -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 |