Home

Awesome

🌐 remote-sshfs.nvim Actions status

🚧 This plugin is currently being developed and may break or change frequently! 🚧

Explore, edit, and develop on a remote machine via SSHFS with Neovim. remote-sshfs.nvim allows you to edit files on remote hosts via SSHFS as if they were local.

Demo

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 mounts files via SSHFS)

✨ Features

⚡️ Requirements

Neovim

Local Machine

Remote Machine

📦 Installation

Install using your favorite package manager

// Using lazy.nvim
return {
 "nosduco/remote-sshfs.nvim",
 dependencies = { "nvim-telescope/telescope.nvim" },
 opts = {
  -- Refer to the configuration section below
  -- or leave empty for defaults
 },
}

Load the extension with telescope

require('telescope').load_extension 'remote-sshfs'

Try the command :RemoteSSHFSConnect to see if remote-sshfs.nvim is installed and configured corrected

⚙️ Configuration

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"
    },
    -- NOTE: Can define ssh_configs similarly to include all configs in a folder
    -- ssh_configs = vim.split(vim.fn.globpath(vim.fn.expand "$HOME" .. "/.ssh/configs", "*"), "\n")
    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,
    },
  },
}

🚀 Usage

Commands

: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.

: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.

Keybinds

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, {})

Use Cases

With this plugin you can:

To learn more about SSH configs and how to write/style one you can read more here

🤝 Contributing

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.

🌟 Credits

📜 License

remote-sshfs.nvim is released under the MIT license. please see the LICENSE file for details.