Serpl

serpl 是一个终端用户界面 (TUI) 应用程序，允许用户在整个文件夹中搜索和替换关键词，类似于 VS Code 中的功能。

https://github.com/yassinebridi/serpl/assets/18403595/348506704-73336074-bfaf-4a9a-849c-bd4aa4e24afc

目录

1. 特性
2. 安装
   • 先决条件
   • 步骤
   • 二进制文件
   • 特定操作系统安装
3. 用法
   • 基本命令
   • 键绑定
   • 配置
4. 面板
   • 搜索输入
   • 替换输入
   • 搜索结果面板
   • 预览面板
5. 快速提示
6. 使用 toggleterm 集成 Neovim
7. 许可证
8. 贡献
9. 鸣谢
10. 类似项目

特性

• 在整个项目文件夹中搜索关键词，具有大小写敏感、AST Grep 等选项。
• 替换关键词，具有保留大小写、AST Grep 等选项。
• 交互式预览搜索结果。
• 键盘导航，提高工作效率。
• 可配置的键绑定和搜索模式。

安装和更新

先决条件

• ripgrep 已安装在你的系统上。
• (可选) 如果你想要使用 AST Grep 功能，可以在你的系统上安装 ast-grep。

步骤

1. 使用 Cargo 安装应用程序

cargo install serpl

• 如果你想使用 AST Grep 功能安装应用程序，可以使用以下命令

  cargo install serpl --features ast_grep
  

2. 运行应用程序

serpl

二进制文件

检查 发布页面 以获取最新的二进制文件。

特定操作系统安装

Brew

serpl 可以使用 Homebrew 安装

brew install serpl

Arch Linux

serpl 可以通过 官方仓库 使用 pacman 安装

pacman -S serpl

Nix/NixOS

serpl 自 24.11 起已包含在 nixpkgs 中，可以通过 Nix 以不同的方式安装。

在独立的 Nix 设置上:

nix profile install nixpkgs#serpl

在 NixOS 上（通过 configuration.nix 或类似方式）

{pkgs, ...}: {
  environment.systemPackages = [pkgs.serpl];
}

在 Home-Manager 上:

{pkgs, ...}: {
  home.packages = [pkgs.serpl];
}

用法

基本命令

• 在当前目录启动应用程序

  serpl
  

• 启动应用程序并指定项目根路径

  serpl --project-root /path/to/project
  

键绑定

默认按键绑定可以通过 config.json 文件进行自定义。

默认按键绑定

配置

serpl 使用配置文件来管理按键绑定和其他设置。默认情况下，可以通过运行 serpl --version 来找到配置文件的路径。您可以使用各种文件格式来配置，如 JSON、JSON5、YAML、TOML 或 INI。

示例配置

{
  "keybindings": {
    "<Ctrl-d>": "Quit",
    "<Ctrl-c>": "Quit",
    "<Tab>": "LoopOverTabs",
    "<Backtab>": "BackLoopOverTabs",
    "<Ctrl-o>": "ProcessReplace"
  }
}

{
  keybindings: {
    "<Ctrl-d>": "Quit",
    "<Ctrl-c>": "Quit",
    "<Tab>": "LoopOverTabs",
    "<Backtab>": "BackLoopOverTabs",
    "<Ctrl-o>": "ProcessReplace",
  },
}

keybindings:
  "<Ctrl-d>": "Quit"
  "<Ctrl-c>": "Quit"
  "<Tab>": "LoopOverTabs"
  "<Backtab>": "BackLoopOverTabs"
  "<Ctrl-o>": "ProcessReplace"

[keybindings]
"<Ctrl-d>" = "Quit"
"<Ctrl-c>" = "Quit"
"<Tab>" = "LoopOverTabs"
"<Backtab>" = "BackLoopOverTabs"
"<Ctrl-o>" = "ProcessReplace"

[keybindings]
<Ctrl-d> = Quit
<Ctrl-c> = Quit
<Tab> = LoopOverTabs
<Backtab> = BackLoopOverTabs
<Ctrl-o> = ProcessReplace

您可以通过修改所选格式的配置文件来自定义按键绑定。

面板

搜索输入

• 输入搜索关键字。
• 切换搜索模式（简单、大小写匹配、整词匹配、大小写整词匹配、正则表达式、AST Grep）。
  • 简单：搜索关键字的全部出现。
  • 大小写匹配：搜索与关键字相同大小写的出现。
  • 整词匹配：搜索与关键字完全匹配的出现。
  • 大小写整词匹配：搜索与关键字完全匹配且大小写相同的出现。
  • 正则表达式：使用正则表达式搜索出现。
  • AST Grep：使用 AST Grep 搜索出现。

[!TIP] 如果当前目录相当大，您必须点击 Enter 以开始搜索。

替换输入

• 输入替换文本。
• 切换替换模式（简单、保留大小写、AST Grep）。
  • 简单：替换关键字的全部出现。
  • 保留大小写：替换关键字的同时保留其大小写。
  • AST Grep：使用 AST Grep 替换出现。

搜索结果面板

• 包含搜索结果的文件列表。
• 导航选择和查看文件。
• 从搜索结果中删除文件。
• 搜索结果数量和当前文件数量。
• 使用 / 键在列表中进行搜索。

预览面板

• 显示选定的文件，并突出显示搜索结果和上下文。
• 导航查看文件中的不同匹配项。
• 删除包含匹配项的单个行。

快速提示

• 使用 Ctrl + b 键组合显示帮助对话框。
• 使用Ctrl + o键组合来处理所有文件的替换。
• 使用r键来处理所选文件或行的替换。
• 使用Ctrl + n键组合在搜索和替换模式之间切换。
• 使用g、G、j和k键在搜索结果之间导航。
• 使用d键删除所选文件或行。

使用 toggleterm 集成 Neovim

查看Neovim的toggleterm.nvim插件，该插件提供了一个可以通过键绑定切换的终端。如果您使用AstroNvim

return {
  "akinsho/toggleterm.nvim",
  cmd = { "ToggleTerm", "TermExec" },
  dependencies = {
    {
      "AstroNvim/astrocore",
      opts = function(_, opts)
        local maps = opts.mappings
        local astro = require "astrocore"
        maps.n["<Leader>t"] = vim.tbl_get(opts, "_map_sections", "t")

        local serpl = {
          callback = function()
            astro.toggle_term_cmd "serpl"
          end,
          desc = "ToggleTerm serpl",
        }
        maps.n["<Leader>sr"] = { serpl.callback, desc = serpl.desc }

        maps.n["<Leader>tf"] = { "<Cmd>ToggleTerm direction=float<CR>", desc = "ToggleTerm float" }
        maps.n["<Leader>th"] = { "<Cmd>ToggleTerm size=10 direction=horizontal<CR>", desc = "ToggleTerm horizontal split" }
        maps.n["<Leader>tv"] = { "<Cmd>ToggleTerm size=80 direction=vertical<CR>", desc = "ToggleTerm vertical split" }
        maps.n["<F7>"] = { '<Cmd>execute v:count . "ToggleTerm"<CR>', desc = "Toggle terminal" }
        maps.t["<F7>"] = { "<Cmd>ToggleTerm<CR>", desc = "Toggle terminal" }
        maps.i["<F7>"] = { "<Esc><Cmd>ToggleTerm<CR>", desc = "Toggle terminal" }
        maps.n["<C-'>"] = { '<Cmd>execute v:count . "ToggleTerm"<CR>', desc = "Toggle terminal" }
        maps.t["<C-'>"] = { "<Cmd>ToggleTerm<CR>", desc = "Toggle terminal" }
        maps.i["<C-'>"] = { "<Esc><Cmd>ToggleTerm<CR>", desc = "Toggle terminal" }
      end,
    },
  },
  opts = {
    highlights = {
      Normal = { link = "Normal" },
      NormalNC = { link = "NormalNC" },
      NormalFloat = { link = "NormalFloat" },
      FloatBorder = { link = "FloatBorder" },
      StatusLine = { link = "StatusLine" },
      StatusLineNC = { link = "StatusLineNC" },
      WinBar = { link = "WinBar" },
      WinBarNC = { link = "WinBarNC" },
    },
    size = 10,
    ---@param t Terminal
    on_create = function(t)
      vim.opt_local.foldcolumn = "0"
      vim.opt_local.signcolumn = "no"
      if t.hidden then
        local toggle = function() t:toggle() end
        vim.keymap.set({ "n", "t", "i" }, "<C-'>", toggle, { desc = "Toggle terminal", buffer = t.bufnr })
        vim.keymap.set({ "n", "t", "i" }, "<F7>", toggle, { desc = "Toggle terminal", buffer = t.bufnr })
      end
    end,
    shading_factor = 2,
    direction = "float",
    float_opts = { border = "rounded" },
  },
}

许可证

本项目采用MIT许可证。有关详细信息，请参阅LICENSE文件。

贡献

(WIP)

鸣谢

• 本项目受到VS Code搜索和替换功能的影响。
• 本项目使用令人惊叹的ratatui.rs库构建，并基于他们的Component Template。
• 感谢ripgrep项目提供搜索功能。
• 感谢ast-grep项目提供AST Grep功能。

类似项目

• repgrep：一个交互式替换器，使得在命令行中轻松查找和替换跨文件变得容易。