Skip to content

Latest commit

 

History

History
237 lines (192 loc) · 9.54 KB

README.zh.md

File metadata and controls

237 lines (192 loc) · 9.54 KB
Raw

workspace-scanner.nvim

English | 简体中文

一个丰富的工作区管理器，它极其注重用户体验及追求最佳性能，它不内置绑定任何 session 插件，但提供了相关钩子来供用户自由绑定

[WIP] 功能已开发完成，且自用过一段时间，文档处于待完善状态

特性

1. 项目定义的灵活性：可以以多种格式定义工作区项目
local workspaces_source = {
  -- 定义一个名为 `web` 的工作区
  web = {
    -- `w_dir` -> `workspace_dir`
    -- 定义一个名为 `ui_libs` 的工作区，它会将 `~/projects/web/__ui-libs__/` 路径下包含 `package.json` 文件的所有子文件夹视为独立的工作区项目
    ui_libs = { w_dir = "~/projects/web/__ui-libs__/", patterns = { "package.json" } },
    -- 定义一个名为 `temp_scripts` 的工作区，它会将 `~/projects/web/__temp__/` 路径下的所有子文件夹视为独立的工作区项目
    temp_scripts = { w_dir = "~/projects/web/__temp__/", patterns = "*" },
  },
  -- 定义一个名为 `nvim` 的工作区
  nvim = {
    -- 定义一个名为 `my_config` 的工作区项目
    my_config = "~/.config/nvim/",
    -- 定义一个名为 `lazy` 的工作区，它会将 `lazy.nvim` 插件安装目录下的所有子文件夹视为独立的工作区项目
    lazy = { w_dir = vim.fn.stdpath("data") .. "/lazy/", patterns = "*" },
    -- 将 `~/project/nvim/` 路径下的所有子文件夹视为 `nvim` 工作区的项目
    { w_dir = "~/project/nvim/", patterns = "*" },
  },
}
2. 项目选择器（Telescope Picker）：包含一个用于显示项目的选择器功能。可以以树形（tree）或扁平（flat）的方式显示项目

  • 树形（tree）

    tree_example.mp4

  • 扁平（flat）

    flat_example.mp4
3. 历史记录功能（History Recent/Pin）：Recent - 记录最近使用情况；Pin - 将常用项目固定住

  • Recent

    history_recent_example.mp4

  • Pin

    history_pin_example.mp4

要求

  • Neovim >= 0.9.0
  • Telescope

安装

lazy.nvim:

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

如何使用？

可通过 我的配置 了解相关信息

  1. 配置工作区项目
local source = {
  web = { w_dir = "..." },
  my_nvim_config = "...",
}
require("workspace-scanner").setup({
  -- ...
  scanner = { source = source },
  -- ...
})
  1. 刷新工作区缓存

扫描器会自动将扫描到的工作区项目进行本地缓存，这样后续在启动时就无需每次都扫描（如果每次启动都扫描会带来大量耗时）

也就是说，后续工作区项目如果有变动，需要手动刷新缓存

require("workspace-scanner").refresh()
  1. 根据自己的喜好弹出 Picker
-- 具体参数内容可阅读 [配置介绍]
require("workspace-scanner").show_picker({ ... })

-- 个人使用情况：
-- 1. 如果要展示所有项目，则采用 Tree式（这样不会带来项目太多的困扰，可以循序渐进）
require("workspace-scanner").show_picker({
  mode = "tree",
  telescope = {
    opts = {
      prompt_title = "All Projects (Tree)",
    },
  },
})
-- 2. 如果只展示最近工作的项目，则采用 Flat式
require("workspace-scanner").show_picker({
  show_history_only = true,
  telescope = {
    opts = {
      prompt_title = "Recent Projects (Flat)",
    },
  },
})
  1. 定制 Picker 选择回调
require("workspace-scanner").setup({
  picker = {
    events = {
      --- @param entry WS.Picker.SelectedEntry
      on_select = function(entry)
        -- `entry.source.dir` 为选中的项目路径
        -- 接下来你可以做自己想做的事了，比如：切换 cwd 为选中的项目路径
        -- vim.cmd("cd " .. entry.source.dir)

        -- 或是刷新 session 等
      end,
    },
  },
})

配置介绍

展开默认配置
--- @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,
    },
  },
}