workspace-scanner.nvim

简体中文 | English

A sophisticated workspace manager, it places great emphasis on user experience and strives for optimal performance. It does not natively bind to any session plugins, but it provides relevant hooks for users to bind freely.

[WIP] The feature development is completed, and it has been used for a while. The documentation is in the process of being perfected.

Features

1. Flexibility of Project Definition: It allows defining workspace projects in multiple formats

local workspaces_source = {
  -- Define a workspace named `web`
  web = {
    -- `w_dir` -> `workspace_dir`
    -- Define a workspace named `ui_libs`, It treats all subfolders containing `package.json` in the `~/projects/web/__ui-libs__/` path as independent workspace projects
    ui_libs = { w_dir = "~/projects/web/__ui-libs__/", patterns = { "package.json" } },
    -- Define a workspace named `temp_scripts`, It treats all the subfolders in the `~/projects/web/__temp__/` path as independent workspace projects
    temp_scripts = { w_dir = "~/projects/web/__temp__/", patterns = "*" },
  },
  -- Define a workspace named `nvim`
  nvim = {
    -- Define a workspace project named `my_config`
    my_config = "~/.config/nvim/",
    -- Define a workspace named `lazy`, It treats all subfolders in the `lazy.nvim` plugin installation directory as independent workspace projects
    lazy = { w_dir = vim.fn.stdpath("data") .. "/lazy/", patterns = "*" },
    -- Treats all subfolders in the `~/project/nvim/` path as projects of the `nvim` workspace
    { w_dir = "~/project/nvim/", patterns = "*" },
  },
}

---

2. Project Selector (Telescope Picker): Contains a picker feature for displaying projects. It can display projects in tree or flat layout

• Tree

  tree_example.mp4

• Flat

  flat_example.mp4

---

3. History Feature (History Recent/Pin): Recent - Records recent usage; Pin - Pins frequently used projects

• Recent

  history_recent_example.mp4

• Pin

  history_pin_example.mp4

---

Requirements

• Neovim >= 0.9.0
• Telescope

Installation

lazy.nvim:

return {
  "xlboy/workspace-scanner.nvim",
  lazy = true,
  ---@type WS.Config
  opts = {},
}

How to use?

You can understand the relevant information through my configuration

1. Configure the Workspace Project

local source = {
  web = { w_dir = "..." },
  my_nvim_config = "...",
}
require("workspace-scanner").setup({
  -- ...
  scanner = { source = source },
  -- ...
})

2. Refresh Workspace Cache

The scanner will automatically cache the scanned workspace projects locally, so there is no need to scan every time at startup (if you scan every time at startup, it will take a lot of time)

In other words, if there are changes in the workspace projects in the future, you need to manually refresh the cache

require("workspace-sccraper").refresh()

3. Present the Picker According to Your Preferences

-- For specific parameter contents, please read [Configuration Introduction]
require("workspace-scanner").show_picker({ ... })

-- Personal use cases:
-- 1. If you want to display all projects, use the Tree mode (this won't cause too many projects to be an issue, and can be progressive)
require("workspace-scanner").show_picker({
  mode = "tree",
  telescope = {
    opts = {
      prompt_title = "All Projects (Tree)",
    },
  },
})
-- 2. If only the recent projects are displayed, use the Flat mode
require("workspace-scanner").show_picker({
  show_history_only = true,
  telescope = {
    opts = {
      prompt_title = "Recent Projects (Flat)",
    },
  },
})

4. Customize Picker Selection Callback

require("workspace-scanner").setup({
  picker = {
    events = {
      --- @param entry WS.Picker.SelectedEntry
      on_select = function(entry)
        -- `entry.source.dir` is the path of the selected project
        -- Now you can do what you want to do, for example: switch cwd to the path of the selected project
        -- vim.cmd("cd " .. entry.source.dir)

        -- or refresh the session, etc.
      end,
    },
  },
})

Configuration Introduction

Expand default configuration

--- @class WS.Config
local _default_config = {
  scanner = {
    source = {},
    cache_path = vim.fn.stdpath("data") .. "/workspace-scanner" .. "/scan-result-cache.json",
    patterns = { "README.md", ".git", ".hg", ".svn", ".project", ".root", "package.json" },
  },
  --- @class WS.Config.Picker
  picker = {
    mode = "flat", --- @type "flat" | "tree"
    flat_opts = {
      --- If true, includes tree history (pin/recent)
      include_tree_history = true,
      separator = " > ",
    },
    tree_opts = {
      --- If true, includes flat history (pin/recent)
      include_flat_history = true,
      workspace = {
        icon = "📁", --- @type string | false
        history_recent = {
          enabled = true,
          --- @type boolean
          --- If true, adopts the latest data from all its project nodes
          derive_from_children = true,
          icon = "🕒", --- @type string | false
        },
      },
      keymaps = {
        back = "<C-h>",
        forward = "<C-l>",
      },
    },
    --- @type nil | WS.Scanner.Result[]
    --- If nil, use scanner cache
    pick_source = nil,
    --- If true, show only history
    show_history_only = false,
    history = {
      recent = {
        enabled = true,
        cache_path = vim.fn.stdpath("data") .. "/workspace-scanner" .. "/picker-recent-history.json",
        keymaps = { delete = "<C-d>" },
        icon = "🕒", --- @type string | false
      },
      pin = {
        enabled = true,
        cache_path = vim.fn.stdpath("data") .. "/workspace-scanner" .. "/picker-pin-history.json",
        keymaps = { toggle = "<C-g>" },
        icon = "📌", --- @type string | false
      },
    },
    telescope = {
      --- Telescope configuration: https://github.com/nvim-telescope/telescope.nvim/blob/master/doc/telescope.txt#L87
      opts = {
        layout_config = { height = 25, width = 110 },
      },
    },
    events = {
      --- Hook executed after selecting elements in Picker
      --- @param entry WS.Picker.SelectedEntry
      on_select = function(entry)
        vim.cmd("cd " .. entry.source.dir)
      end,
    },
  },
}