🚧 (ALPHA/UNSTABLE) This plugin is currently being developed and may break or change frequently! 🚧
Explore, edit, and develop on a remote machine via SSHFS with Neovim. Loosely based on the VSCode extension Remote - SSH. (Note: this plugin does not install packages on the remote server, instead it conducts finds, greps, etc over SSH and accesses files via SSHFS)
Neovim (v0.7.0) or the
latest neovim nightly commit is required for remote-sshfs.nvim
to work because of its dependencies.
Using vim-plug
Plug 'nosduco/remote-sshfs.nvim'
Using dein
call dein#add('nosduco/remote-sshfs.nvim')
Using packer.nvim
use {
'nosduco/remote-sshfs.nvim',
requires = { {'nvim-telescope/telescope.nvim'} } -- optional if you declare plugin somewhere else
}
Using lazy.nvim
-- init.lua:
{
'nosduco/remote-sshfs.nvim',
}
-- plugins/telescope.lua:
return {
'nosduco/remote-sshfs.nvim',
dependencies = { 'nvim-telescope/telescope.nvim' } -- optional if you declare plugin somewhere else
}
require('remote-sshfs').setup({})
require('telescope').load_extension 'remote-sshfs'
Try the command :RemoteSSHFSConnect
to see if remote-sshfs.nvim
is installed and configured corrected
This plugin allows you to edit files on remote hosts via SSHFS as if they were local.
With this plugin you can:
- Connect and mount a remote host via SSHFS using the
:RemoteSSHFSConnect
command. This command will trigger a picker to appear where you can select hosts that have been parsed from your SSH config files. Upon selecting a host, remote-sshfs will mount the host (by default at~/.sshfs/<hostname>
) and change the current working directory to that folder. Additionally, by default, once vim closes the mount will be automatically unmounted and cleaned. - Disconnect from a remote host that you're current connected to using the
:RemoteSSHFSDisconnect
command - Select a SSH config to edit via a picker by using the
:RemoteSSHFSEdit
command - Utilize Telescope Find Files functionality completely remote via SSH by using the
:RemoteSSHFSFindFiles
command (Note: the remote server must have either ripgrep, fd/fdfind, or the where command) - Utilize Telescope Live Grep functionality completely remote via SSH by using the
:RemoteSSHFSLiveGrep
command (Note: the remote server must have ripgrep installed)
Note: Currently only parsing hosts is supported, the ability to pass a host via the above commands will eventually be added
To learn more about SSH configs and how to write/style one you can read more here
For conveninece, it is recommended to setup keymappings for these commands.
Setup keymappings using Lua:
local api = require('remote-sshfs.api')
vim.keymap.set('n', '<leader>rc', api.connect, {})
vim.keymap.set('n', '<leader>rd', api.disconnect, {})
vim.keymap.set('n', '<leader>re', api.edit, {})
-- (optional) Override telescope find_files and live_grep to make dynamic based on if connected to host
local builtin = require("telescope.builtin")
local connections = require("remote-sshfs.connections")
vim.keymap.set("n", "<leader>ff", function()
if connections.is_connected then
api.find_files()
else
builtin.find_files()
end
end, {})
vim.keymap.set("n", "<leader>fg", function()
if connections.is_connected then
api.live_grep()
else
builtin.live_grep()
end
end, {})
This section should help you explore and configure remote-sshfs.nvim
to your liking
Here is an example setup with the default config. You do not have to supply a configuration, use this as a reference.
require('remote-sshfs').setup{
connections = {
ssh_configs = { -- which ssh configs to parse for hosts list
vim.fn.expand "$HOME" .. "/.ssh/config",
"/etc/ssh/ssh_config",
-- "/path/to/custom/ssh_config"
},
sshfs_args = { -- arguments to pass to the sshfs command
"-o reconnect",
"-o ConnectTimeout=5",
},
},
mounts = {
base_dir = vim.fn.expand "$HOME" .. "/.sshfs/", -- base directory for mount points
unmount_on_exit = true, -- run sshfs as foreground, will unmount on vim exit
},
handlers = {
on_connect = {
change_dir = true, -- when connected change vim working directory to mount point
},
on_disconnect = {
clean_mount_folders = false, -- remove mount point folder on disconnect/unmount
},
on_edit = {}, -- not yet implemented
},
ui = {
select_prompts = false, -- not yet implemented
confirm = {
connect = true, -- prompt y/n when host is selected to connect to
change_dir = false, -- prompt y/n to change working directory on connection (only applicable if handlers.on_connect.change_dir is enabled)
},
},
log = {
enable = false, -- enable logging
truncate = false, -- truncate logs
types = { -- enabled log types
all = false,
util = false,
handler = false,
sshfs = false,
},
},
}
Here's a list of the available commands and variations:
:RemoteSSHFSConnect
: Use this command to open the host picker and connect to a remote host (parsed from ssh configs)
:RemoteSSHFSConnect <[user@]host>:/path -p <port>
: Use this command to directly connect to a host with optional user, path, and port variables like you would with scp
or sshfs
.
- Examples:
:RemoteSSHFSConnect tony@server:/srv -p 1234
,:RemoteSSHFSConnect server
,:RemoteSSHFSConnect tony@server
:RemoteSSHFSDisconnect
: Use this command to disconnect from a connected host
:RemoteSSHFSEdit
: Use this command to open the ssh config picker to open and edit ssh configs
:RemoteSSHFSFindFiles
: Use this command to initiate a telescope find files window which operates completely remotely via SSH and will open buffers referencing to your local mount
:RemoteSSHFSLiveGrep
: Use this command to initiate a telescope live grep window which operates completely remotely via SSH and will open buffers referencing to your local mount
Integrations are key to the usefulness of remote-sshfs.nvim
and many more are to come.
Currently, integrations are being developed and will be released soon.
If you find a bug or have a suggestion for how to improve remote-sshfs.nvim or additional functionality, please feel free to submit an issue or a pull request. We welcome contributions from the community and are committed to making remote-sshfs.nvim as useful as possible for everyone who uses it.
remote-sshfs.nvim is released under the MIT license. please see the LICENSE file for details.