Whaler

Lost in the ocean of your unordered and unorganized file-explorer looking for that project? Whaler has you covered.

What is Whaler?

Whaler is a minimalist project / directory navigator. It provides a clean interface to work with projects.

It is based on the concept of tmux-windowizer from ThePrimeagen which uses a set of directories and fzf to move to another directory in a new tmux session.

Whaler offers a fast experience to move between projects without having much hassle, while giving users the ability to customize their experience as much as possible.

whaler-example

The gist of whaler.nvim is simple:

Set the parent directories where projects live. All the subdirectories will be considered projects for Whaler (directories).
If there are single directories you need as projects you can also define them (oneoff_directories)
Execute Whaler to move between projects!
You can customize Whaler to make it your own project navigator. See Options and API for advanced usage.

Getting Started

Whaler is a neovim project / directory navigator.

Dependencies

Neovim >= v0.9.0)

Optional pickers:

Minimal installation setup

Using lazy.nvim:

return {
    "SalOrak/whaler",
    opts = {
        -- Directories to be used as parent directories. Their subdirectories 
        -- are considered projects for Whaler.
        directories = {
            "path/to/parent/project", 
            { path = "path/to/another/parent/project", alias = "An alias!"}
        },
        -- Directories to be directly used as projects. No subdirectory lookup.
        oneoff_directories = {
            { path = "~/.local/share/nvim/lazy", alias = "Neovim Installation"},
            { path = "~/.config/", alias = "Config directory"}
        },

        -- Picker to use. By default uses `telescope` for compatibility reasons.
        -- Options are 'telescope', 'fzf_lua' and 'vanilla' (uses `vim.ui.input`).
        picker = "telescope"
    },
}

Or you can also set up whaler.nvim as a Telescope extension.

return {
	{
        "nvim-telescope/telescope.nvim",
		dependencies = {
            "salorak/whaler.nvim", -- Make sure to add `whaler` as a dependency.
        }, 
        config = function()
            local t = require("telescope")

            t.setup({
                --- ... your telescope configuration .. ---
                extensions = {
                    whaler = {
                        -- Directories to be used as parent directories. Their subdirectories 
                        -- are considered projects for Whaler.
                        directories = {
                            "path/to/parent/project", 
                            { path = "path/to/another/parent/project", alias = "An alias!"}
                        },
                        -- Directories to be directly used as projects. No subdirectory lookup.
                        oneoff_directories = {
                            { path = "~/.local/share/nvim/lazy", alias = "Neovim Installation"}
                            { path = "~/.config/", alias = "Config directory"}
                        },

                        -- Picker to use. By default uses `telescope` for compatibility reasons.
                        -- Options are 'telescope', 'fzf_lua' and 'vanilla' (uses `vim.ui.input`).
                        picker = "telescope"

                    },
                }
            })

            -- Don't forget to load Whaler as an extension!
            t.load_extension("whaler")
        end

Usage example

Whaler does not have any mappings by default. It is up to you to create any mappings.

You can also call the Whaler and WhalerSwitch user commands.

In the configuration file:

-- Telescope setup()
local telescope = require('telescope')

telescope.setup({
    -- Your telescope setup here...
    extensions = {
        whaler = {
            -- Whaler configuration
            directories = { "path/to/dir", "path/to/another/dir", { path = "path/to/yet/another/dir", alias = "yet" } },
            -- You may also add directories that will not be searched for subdirectories
            oneoff_directories = { "path/to/project/folder",  { path = "path/to/another/project", alias = "Project Z" } },
        }
    }
})
-- More config here
telescope.load_extension("whaler")
--

-- Open whaler using <leader>fw
vim.keymap.set("n", "<leader>fw", function()
    local w = telescope.extensions.whaler.whaler
    w({
        -- Settings can also be called here.
        -- These would use but not change the setup configuration.
    })
 end,)

-- Or directly
vim.keymap.set("n", "<leader>fw", telescope.extensions.whaler.whaler)

In addition to passing strings into the directories and oneoff_directories parameters above one may also choose to use tables such as {path="/path/to/dir", alias="Personal Projects"}, this will modify the text presented in the selection UI to show [Personal Projects] theproject instead of the full path to each of the project folders.

Now, pressing <leader>fw will open a Telescope picker with the subdirectories of the specified directories for you to select.

Options

Whaler.nvim shines the most when your personal touch is added. Below is the default and complete list of configuration options. Here is the list of a default configuration:

whaler = {
    -- Path directories to search. By default the list is empty.
    directories = { "/home/user/projects", { path = "/home/user/work", alias = "work" } }, 

    -- Path directories to append directly to list of projects. By default is empty. 
    oneoff_directories = { "/home/user/.config/nvim" }, 

    -- Whether to automatically open file explorer. By default is `true`
    auto_file_explorer = true,

    -- Whether to automatically change current working directory. By default is `true`
    auto_cwd = true, 

    -- Minimum verbosity level to notify when something happens. By default is WARN.
    -- See `vim.log.levels` 
    verbosity = vim.log.levels.WARN,

    -- Automagically creates a configuration for the file explorer of your choice. 
    -- Options are "fzf_lua_explorer", "netrw"(default), "nvimtree", "neotree", "oil", "telescope_file_browser", "rnvimr"
    file_explorer = "netrw", 

    -- Show hidden directories or not (default false)
    hidden = false,

     -- (OPTIONAL) If you want to fully customize the file explorer configuration,
     -- below are all the possible options and its default values.
    file_explorer_config = {

        -- Plugin. Should be installed.
        plugin_name = "netrw", 

        -- The plugin command to open.
        -- Command must accept a path as parameter
        -- Prefix string to be appended after the command and before the directory path. 
        command = "Explorer", 
                              
        -- Example: In the `telescope_file_browser` the value is ` path=`.
        --          The final command is `Telescope file_browser path=/path/to/dir`.
        -- By default is " " (space)
        prefix_dir = " ",     
    },

    -- Which picker to use. One of 'telescope', 'fzf_lua' or 'vanilla'. Default to 'telescope'
    picker = "telescope", 

    -- Picker options
    -- Options to pass to Telescope. Below is the default.
    telescope_opts = {
        results_title = false,
        layout_strategy = "center",
        previewer = false,
        layout_config = {
            --preview_cutoff = 1000,
            height = 0.3,
            width = 0.4,
        },
        sorting_strategy = "ascending",
        border = true,
    },
    -- For compatiblity you can also use `theme` directly to modify Telescope. 
    theme = {},
 
    -- Options to pass to FzfLua directly. See
    -- https://github.com/ibhagwan/fzf-lua?tab=readme-ov-file#customization for
    -- options. Below is the defaults.
    fzflua_opts= {
        prompt = "Whaler >> ",
        --- You can modify the actions! Go ahead!
        actions = {
            ["default"] = function(selected)
                    local Whaler = require'whaler'
                    local dirs_map = State:get().dirs_map

                    local display = selected[1] 
                    local path = dirs_map[selected[1]]

                    -- For changing projects and
                    Whaler.select(path, display)
                end

        },
        fn_format_entry = function(entry)
            if entry.alias then
                return (
                        "["
                        .. entry.alias
                        .. "] "
                        .. vim.fn.fnamemodify(entry.path, ":t")
                       )
            end
            return entry.path
            end,
    },
}

By default Whaler.nvim changes the current working directory (cwd) to the selected directory AND opens the file explorer (netrw by default).

Changing auto_cwd to false will make Whaler to only open the file explorer in the selected directory while maintaining the previous current working directory.

Changing auto_file_explorer to false while keeping auto_cwd enabled will make Whaler to change the current wo

Whaler.nvim

Install / Use

README