开发工具CLI【免费下载链接】pecoSimplistic interactive filtering tool项目地址https://gitcode.com/gh_mirrors/pe/peco点击查看免费下载peco是一款用 Go 编写的简化版交互式过滤工具Simplistic interactive filtering tool它从 stdin 或文件读取行内容让你一边输入查询一边实时过滤最终把选中的行输出到 stdout 供下游命令继续消费。本文以仓库内的 CLI 参考文档.claude/docs/cli.md为骨架结合cmd/peco/peco.go、options.go、peco.go 与 README.md 的源码实现完整梳理 peco 的命令行入口、全部参数语义、退出码约定以及输入输出协议帮助你掌握 peco 在脚本、管道与日常终端工作流中的正确用法。入口点与启动流程peco 的程序入口位于 cmd/peco/peco.go。main()先注册一个recover()兜底随后调用_main()_main()的核心逻辑只有三步创建context用于在整个生命周期内协调取消操作调用peco.New()构造全局的Peco实例见 peco.go内部初始化内存行缓冲、ID 生成器、查询执行状态、tcell 屏幕与选择集合调用cli.Run(ctx)启动整套 TUI 管线并根据返回错误类型决定进程退出码。Run()peco.go内部依次执行Setup()初始化默认配置 → 解析命令行参数 → 读取配置文件 → 将参数与配置合并应用到运行时ApplyConfig→ 创建消息总线parseCommandLine()peco.go使用go-flags解析argv同时处理--help与--version的立即返回逻辑若未指定--rcfile则调用config.LocateRcfile自动查找配置文件SetupSource()peco.go确定输入来源并启动读取协程阻塞到收到第一行数据启动屏幕、输入循环、视图循环与过滤循环四个 goroutine随后进入-ctx.Done()等待用户操作结束。从源码结构看命令行参数解析是整个启动流程中最早的一环其解析结果直接影响后续配置加载与运行时状态组装因此理解每个参数的语义是使用 peco 的第一步。命令行参数总览CLIOptions结构体options.go以go-flags的 struct tag 定义了全部命令行参数。下表为完整清单与 CLI 文档逐项对应Flag类型说明--help-hbool显示帮助信息并退出--versionbool显示版本号并退出--querystring启动时的初始查询字符串--rcfilestring配置文件路径--buffer-size-bint搜索缓冲保留的最大行数0 表示不限--nullbool使用 NUL\0作为行分隔/结果标记--initial-indexint初始光标位置0 起--initial-filterstring初始过滤器名称--filter[]string注册的过滤器列表按轮转顺序可重复覆盖配置项Filters未知名称报错--negation-prefix*string排除行的查询词前缀默认-传空串关闭负向匹配覆盖配置项NegationPrefix--promptstring查询行提示符--layoutstring布局top-down、bottom-up、top-down-query-bottom--select-1bool输入仅 1 行时自动选中并立即退出--exit-0bool输入为空时立即以状态 1 退出部分文档中写作--exit-zero源码 tag 为long:exit-0指同一开关--select-allbool全选所有行并立即退出--on-cancelstring取消行为success/error--selection-prefixstring选中行的前缀标记默认用颜色区分--execstring将选中内容通过管道交给指定命令执行--print-querybool输出结果时把查询字符串作为第一行打印--colorColorMode颜色模式auto、none--heightstring终端高度规格如10、50%此外源码中还定义了文档表格未列出、但实际可用的-f, --follow跟随流式输入自动滚动类似tail -f见 options.go阅读时可一并参考。参数解析完成后会执行Validate()options.go当--layout非空时必须命中config.IsValidLayoutType中定义的三种布局之一否则返回unknown layout错误。参数详解与源码级语义基本信息类--help、--version--help会通过反射遍历CLIOptions的 struct tag 自动生成对齐的帮助文本options.go并返回一个可忽略错误让进程以 0 退出--version则打印peco version v0.6.0 (built with go1.x)格式的版本信息版本号定义于 peco.go。查询与过滤类--query string设置启动时的初始查询。设置后游标会自动定位到查询串末尾utf8.RuneCountInString见 peco.go并在 peco 就绪后立即执行一次过滤。适合在脚本中提前猜出最可能的查询词如cd $(ghq list --full-path | peco --query peco)。-b, --buffer-size num限制 peco 在任何时刻持有的行数上限0默认表示不限制。对可能无限增长的流式输入尤其重要可防止内存被耗尽。--null启用 NUL 分隔模式。每行输入中\0之前的部分用于显示与匹配\0之后的部分作为退出时输出的结果。该开关在源码中对应enableSep字段并会传递给Source与外部过滤器peco.go。--initial-index int0 起始的初始光标行号。例如想从第二行开始选中传入1peco.go 中 0才生效。--initial-filter name指定启动时使用的过滤器名字须为IgnoreCase、CaseSensitive、SmartCase、IRegexp、Regexp、Fuzzy之一或自定义过滤器名。若名字无效populateInitialFilter会报failed to set filter错误。--filter name可重复指定按给定顺序注册过滤器peco.RotateFilter默认绑定C-r只在这几个过滤器间轮转。默认情况下注册全部内置过滤器及所有自定义过滤器一旦指定--filter则以命令行为准覆盖配置文件Filters段。未知名字会触发错误并列出可接受的过滤器名peco.go。注意--initial-filter指定的名字必须属于已注册集合。--negation-prefix string定义排除词前缀默认-。空值关闭负向匹配所有词按原样匹配换其他字符如!则保留负向匹配同时让连字符参与字面匹配。该值最终经filter.WithNegationPrefix注入每个过滤器filter/option.go负向词通过正则排除实现isExcluded见 filter/filter.go。命令行写法建议带--negation-prefix否则以-开头的值会被当作新选项解析。界面与布局类--prompt string查询行提示符默认QUERYconfig.DefaultPrompt见 config/config.go。命令行优先级高于配置文件的Prompt。--layout type三种取值对应三种屏幕排布——top-down默认提示符在顶、列表居中、状态行在底、bottom-up列表逆序显示在顶、提示符在下、top-down-query-bottom列表在顶、查询提示符沉底。对 percol 用户而言--layoutbottom-up约等于--prompt-bottom --result-bottom-up。--height num|percentage让 peco 以内联模式在终端底部渲染指定行数而不是占满整个备用屏幕从而保留上方滚动历史类似 fzf 的--height。绝对值--height 5表示 5 行结果区提示符与状态栏自动追加共 7 行百分比--height 50%表示占终端总高度含提示符与状态栏的比例。最小有效高度为 3 行1 行结果 提示符 状态栏超出终端高度会被截断——这些规则由 config/height.go 的Resolve实现ChromLines 2常量即提示符与状态栏占用的行数。内联模式还会设置环境变量TCELL_ALTSCREENdisable阻止 tcell 使用备用屏幕缓冲异常终止如SIGKILL后可能需要手动unset TCELL_ALTSCREEN。--color auto|none控制输入中 ANSI SGR 转义序列的解析与渲染。auto默认保留git log --color、rg --coloralways等管道输入的颜色none则剥离转义序列。匹配过滤始终针对剥离后的纯文本进行输出时保留原始 ANSI 码。该开关只影响输入 ANSI 颜色这一层与配置Style控制的 UI 样式选中高亮、匹配高亮等相互独立。--selection-prefix string用指定前缀代替变色来标记当前选中行实验性默认仍以颜色区分。等价于配置文件中的SelectionPrefix。行为控制类--select-1当且仅当输入恰好 1 行时自动选中该行并立即退出不进入交互界面。源码在selectOneAndExitIfPossiblepeco.go中通过 CAS 原子操作保证多 goroutine 并发下只触发一次。若输入有多行则照常展示选择界面。--exit-0输入为 0 行时立即以状态 1 退出。exitZeroIfPossiblepeco.go检查缓冲区为空后构造exitStatusError{status: 1}。--select-all全选所有输入行并立即退出不展示选择界面selectAllAndExitIfPossiblepeco.go。当同时存在初始查询时会先执行查询再全选当前结果。--on-cancel success|error定义用户按 Esc 取消时的退出语义。默认success兼容历史行为取消也返回 0error则返回非零状态。配置项OnCancel与其等价命令行优先。OnCancelBehavior的合法值校验见 config/config.go。上述三个立即退出开关--select-1、--exit-0、--select-all都由startEarlyExitHandlerspeco.go以独立 goroutine 等待输入源SetupDone()后触发适合批量脚本场景。输出类--print-query退出时把最终查询字符串作为输出的第一行打印。正常结束回车确认时即使没有匹配也会打印按 Esc 取消时不会打印。实现见PrintResultspeco.go。--exec command不再选出即退出而是把当前选中的行通过 stdin 管道交给外部命令经/bin/sh -c或cmd /c执行。命令执行完毕后控制权返回 peco可继续浏览搜索缓冲并重复执行此时要真正退出 peco 需按 EscCancel。peco 自身最终的退出状态码继承自该外部命令的退出状态——这就是文档中Custom — from--execcommand exit status的来源。退出码语义peco 的退出码由 cmd/peco/peco.go 中的错误分类决定退出码场景0成功有行被选中并输出0取消默认行为--on-cancel success1取消且指定了--on-cancel error自定义--exec指定命令的退出状态码底层机制Run()返回的p.Err()会被包装为特定错误类型——collectResultsError触发结果打印并以 0 退出ignorableError如--help、--version直接返回 0exitStatusError如--exit-0的空输入、--exec的子命令状态携带ExitStatus()返回值其余未知错误打印到 stderr 并以 1 退出。输入处理stdin、文件与流式输入SetupSource的输入选择逻辑peco.go遵循三条规则位置参数指向文件命令行剩余参数p.args[1]起存在时直接os.Open该文件作为输入默认读 stdin无位置参数且 stdin 不是 TTY 时从 stdin 读取并把该来源标记为isInfinite true——这意味着后续查询无法使用批量模式只能采用发送即查 超时回调的流式策略sendQuery与waitAndCall见 peco.go既无文件也无管道则报错提示you must supply something to work with via filename or stdin。典型用法# stdin 管道 ps aux | peco # 直接读文件 peco /var/log/nginx/access.log # 无限流 缓冲上限 journalctl -f | peco --buffer-size 1000流式输入isInfinite还会影响--select-1的判定时机由于无法等待过滤管线结束源码采用 2 秒超时 100ms 轮询的waitAndCall机制做尽力而为的单行检查peco.go。输出处理选中行、查询首行与命令管道退出时PrintResultspeco.go按以下顺序产出若当前没有任何选中行则把光标所在行自动加入选择集保证总有一条结果若启用--print-query先把查询字符串写入缓冲并追加换行遍历选择集按原始顺序Ascend每行调用line.Output()输出到 stdout逐行换行分隔。三种输出模式的对比# 模式一选中行逐行输出到 stdout ps aux | peco # 模式二查询串作为第一行输出 ps aux | peco --print-query --query root # 输出示例 # root # root 12345 ... # 模式三选中内容交给下游命令 ls *.go | peco --exec wc -l在--null模式下输出的是每行\0之后的结果段适合显示 A 输出 B的映射场景。参数优先级命令行 配置文件 内置默认值从ApplyConfigpeco.go的赋值顺序可以清晰归纳出 peco 的优先级约定命令行选项优先于配置文件配置文件优先于内置默认值。典型示例--negation-prefix先取filter.DefaultNegationPrefix-再被配置NegationPrefix覆盖最后被命令行覆盖--height命令行OptHeight非空则用之否则取配置Height--filter/--initial-filterOptFilters为空才回落到p.config.FiltersOptInitialFilter为空才回落p.config.InitialFilter--followopts.OptFollow || p.config.Follow合并生效--prompt、--on-cancel、--selection-prefix同理。配置文件支持 JSON 与 YAML按扩展名区分见 config/config.go未指定--rcfile时按顺序查找$XDG_CONFIG_HOME/peco/config.{json,yaml,yml}、~/.config/peco/...、$XDG_CONFIG_DIRS各目录及~/.peco/...config/config.go。实战速查# 最基础管道过滤回车选中Esc 取消 ps aux | peco # 带初始查询与提示符适合脚本预判 history | peco --query git --prompt HIST # 多选并交给命令配合 C-Space 多选 ls | peco --exec xargs cat # 流式日志跟随 沉底布局 journalctl -f -n 1000 | peco --follow --layout top-down-query-bottom # 只注册两个过滤器轮转 peco --filter IgnoreCase --filter Fuzzy input.txt # 禁用负向匹配历史记录里满是连字符的场景 history | peco --negation-prefix # 内联高度模式保留终端滚动历史 ls | peco --height 40%小结peco 的 CLI 设计遵循小而锐的哲学入口极简New()Run(ctx)参数全部收敛在CLIOptions结构体中退出码、输入来源与输出格式都有清晰而稳定的契约。理解这些命令行语义——尤其是--filter/--negation-prefix/--height/--exec这类与配置项联动的参数以及命令行 配置 默认值的优先级规则——能让你在 shell 脚本、日志检索与文件导航场景中把 peco 用出最大的生产力。赞分享开发工具CLI【免费下载链接】pecoSimplistic interactive filtering tool项目地址https://gitcode.com/gh_mirrors/pe/peco点击查看免费下载相关推荐Repomix CLI 命令行选项完全参考从输入输出到安全、Token 计数与 Agent SkillsRepomix CLI 命令行选项完全参考从输入输出到安全、Token 计数与 Agent Skills Repomix 是一款将整个代码仓库打包为单个 AI开发工具MCP 服务AI 应用Stylelint 命令行接口CLI完全指南参数详解、实战用法与退出码Stylelint 命令行接口CLI完全指南参数详解、实战用法与退出码 Stylelint 是一款强大的 CSS 检查器linter帮助开发者避免样代码质量静态分析前端UniGetUI 命令行接口CLI完全指南动词命令语法、自动化 IPC 传输与退出码详解UniGetUI 命令行接口CLI完全指南动词命令语法、自动化 IPC 传输与退出码详解 导读 UniGetUI 在 2026 年发布的 CLI 重构中桌面应用开发工具跨平台上一篇如何通过Zotero-GPT实现文献管理的智能革命从手动整理到AI驱动的知识发现下一篇如何在ComfyUI中快速实现AI换脸ReActor Node完整入门指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 的语法糖，但代码量减少了约 40%)
