Otree.nvim

🌲 Otree.nvim

Otree.nvim is a lightweight and customizable file tree explorer for Neovim, built for speed, simplicity, and seamless user experience. It optionally integrates with oil.nvim to provide an elegant and efficient file operations workflow.

✨ Features

• Fast and responsive file tree using fd (optional)
• Optional integration with oil.nvim for enhanced file operations
• Supports icons from mini.icons, nvim-web-devicons, or a default fallback
• Optional Git and LSP signs to show file changes and diagnostics
• Highly customizable keybindings and appearance
• Optional Netrw hijack for a cleaner startup experience
• Toggle visibility for hidden and ignored files
• Floating window support with adjustable dimensions

⚙️ Requirements

• Neovim 0.10+

Optional Dependencies

• fd - For faster directory traversal
• oil.nvim - For file operations (create, delete, move, rename files/directories)

📦 Installation

Using lazy.nvim:

return {
    "Eutrius/Otree.nvim",
    lazy = false,
    dependencies = {
        -- Optional: Enhanced file operations
        "stevearc/oil.nvim",
        -- Optional: Icon support
        -- { "echasnovski/mini.icons", opts = {} },
        -- "nvim-tree/nvim-web-devicons",
    },
    config = function()
        require("Otree").setup()
    end
}

⚙️ Configuration

Here is the default configuration, which can be customized to suit your preferences:

require("Otree").setup({
    win_size = 30,
    open_on_startup = false,
    use_default_keymaps = true,
    hijack_netrw = true,
    show_hidden = false,
    show_ignore = false,
    cursorline = true,
    focus_on_enter = false,
    open_on_left = true,
    git_signs = false,
    lsp_signs = false,
    oil = "float",
    ignore_patterns = {},

    keymaps = {
        ["<CR>"] = "actions.select",
        ["l"] = "actions.select",
        ["h"] = "actions.close_dir",
        ["<Esc>"] = "actions.close_win",
        ["<C-h>"] = "actions.goto_parent",
        ["<C-l>"] = "actions.goto_dir",
        ["<M-h>"] = "actions.goto_home_dir",
        ["cd"] = "actions.change_home_dir",
        ["L"] = "actions.open_dirs",
        ["H"] = "actions.close_dirs",
        ["o"] = "actions.oil_dir",
        ["O"] = "actions.oil_into_dir",
        ["t"] = "actions.open_tab",
        ["v"] = "actions.open_vsplit",
        ["s"] = "actions.open_split",
        ["."] = "actions.toggle_hidden",
        ["i"] = "actions.toggle_ignore",
        ["r"] = "actions.refresh",
        ["f"] = "actions.focus_file",
        ["?"] = "actions.open_help",
    },

    tree = {
        space_after_icon = " ",
        space_after_connector = " ",
        connector_space = " ",
        connector_last = "└",
        connector_middle = "├",
        vertical_line = "│",
    },

    icons = {
        title = " ",
        default_file = "",
        default_directory = "",
        empty_dir = "",
        trash = " ",
        keymap = "⌨ ",
        oil = " ",
    },

    highlights = {
        directory = "Directory",
        file = "Normal",
        tree = "Comment",
        title = "Title",
        float_normal = "NormalFloat",
        float_border = "FloatBorder",
        link_path = "Comment",
        git_ignored = "NonText",
        git_untracked = "DiagnosticInfo",
        git_modified = "DiagnosticWarn",
        git_added = "DiagnosticHint",
        git_deleted = "DiagnosticError",
        git_conflict = "DiagnosticError",
        git_renamed = "DiagnosticHint",
        git_copied = "DiagnosticHint",
        lsp_warn = "DiagnosticWarn",
        lsp_info = "DiagnosticInfo",
        lsp_hint = "DiagnosticHint",
        lsp_error = "DiagnosticError",
    },

    float = {
        center = true,
        width_ratio = 0.4,
        height_ratio = 0.7,
        padding = 2,
        cursorline = true,
        border = "rounded",
    },
})

🗝️ Keybindings

*Requires oil.nvim for file operations

🧪 User Commands

🎨 Highlight Groups

Otree defines the following highlight groups that you can customize to match your colorscheme:

🔧 Git Signs

Otree uses a set of icons and highlight groups to visually indicate Git status within the tree view.

🔧 Lsp Signs

Otree uses a fix icon "•" and a set of highlight groups to visually indicate Lsp diagnostics within the tree view.

⚙️ Oil.nvim Integration

Otree can optionally integrate with oil.nvim for enhanced file management capabilities.

⚠️ Note: Without oil.nvim, there are no file operations available (create, delete, move, rename). Oil integration is required for any file management beyond basic navigation and opening.

Automatic Configuration

If oil.nvim is installed but not already configured, Otree will automatically set it up with these optimized defaults:

require("oil").setup({
    default_file_explorer = false,
    skip_confirm_for_simple_edits = true,
    delete_to_trash = true,
    cleanup_delay_ms = false,
})

If Oil is already configured, Otree respects your existing setup and will not override any settings.

Opening Modes

You can configure how Oil opens using the oil option in your Otree setup:

require("Otree").setup({
    oil = "float"  -- Opens Oil in a floating window (default)
    -- Any other value opens Oil directly inside the tree window
})

Hidden Files Synchronization

Toggling hidden files in Otree automatically syncs with Oil's view_options.show_hidden setting, ensuring consistent visibility across both interfaces.

Dynamic Titles

Oil views display dynamically generated titles with icons and relative paths for better context and navigation.

⚠️ Important Note

Do not use oil_preview when Oil is open in floating mode. This may cause rendering or focus issues. Close floating Oil windows before using preview functionality.

🔧 Fallback Behavior

When optional dependencies are not available:

• Without fd: Falls back to basic directory listing (slower performance)
• Without oil.nvim: No file operations available - only navigation and opening files is supported
• Without icon plugins: Uses simple default icons for files and directories