{"id":16512894,"url":"https://github.com/srstevenson/vim-picker","last_synced_at":"2025-04-13T04:59:22.278Z","repository":{"id":14373389,"uuid":"64086009","full_name":"srstevenson/vim-picker","owner":"srstevenson","description":"Fuzzy picker for file, buffer, and tag navigation in Vim and Neovim. Lightweight and Unix-philosophy compliant.","archived":true,"fork":false,"pushed_at":"2024-10-19T14:11:21.000Z","size":178,"stargazers_count":198,"open_issues_count":0,"forks_count":17,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-13T04:59:16.872Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/srstevenson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-07-24T21:16:20.000Z","updated_at":"2025-04-11T18:12:58.000Z","dependencies_parsed_at":"2024-11-16T19:02:45.721Z","dependency_job_id":"773e2232-5f1b-4f7c-8ff1-d33728f920e1","html_url":"https://github.com/srstevenson/vim-picker","commit_stats":{"total_commits":152,"total_committers":14,"mean_commits":"10.857142857142858","dds":"0.16447368421052633","last_synced_commit":"25c16a416764739ac77936ff1285ce2fb36ed7f3"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srstevenson%2Fvim-picker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srstevenson%2Fvim-picker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srstevenson%2Fvim-picker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/srstevenson%2Fvim-picker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/srstevenson","download_url":"https://codeload.github.com/srstevenson/vim-picker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665758,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["file-picker","fuzzy-search","neovim","neovim-plugin","vim","vim-plugin"],"created_at":"2024-10-11T16:06:26.007Z","updated_at":"2025-04-13T04:59:22.259Z","avatar_url":"https://github.com/srstevenson.png","language":"Vim Script","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"images/vim-picker.png\" width=300\u003e\u003c/p\u003e\n\n\u003e [!NOTE]\n\u003e\n\u003e vim-picker is no longer actively maintained. It is implemented and configured\n\u003e in Vimscript as it was developed before the addition of the Lua API to Neovim,\n\u003e and predates Neovim features such as floating windows. If you're looking for a\n\u003e modern fuzzy picker for Neovim, [Telescope][telescope] is a popular choice.\n\n[vim-picker] is a fuzzy picker for [Neovim] and [Vim].\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://user-images.githubusercontent.com/5845679/50046422-d29d5280-009a-11e9-94a8-bfe57972cc5a.gif\" width=\"600\" /\u003e\n\u003c/p\u003e\n\nvim-picker allows you to search for and select files, buffers, and tags using a\nfuzzy selector such as [`fzy`][fzy], [`pick`][pick], or [`selecta`][selecta]. It\nhas advantages over plugins with a similar purpose such as [ctrlp.vim] and\n[Command-T]:\n\n- It uses the embedded terminal emulator when available (this requires\n  [Neovim][nvim-terminal] or [Vim 8.1][vim-terminal]), so the fuzzy selector\n  does not block the UI. Whilst selecting an item you can move to another\n  buffer, edit that buffer, and return to the fuzzy selector to continue where\n  you left off.\n- It adheres to the Unix philosophy, and does not reimplement existing tools.\n  File listing is achieved using the best tool for the job: `git` in Git\n  repositories and [`fd`][fd] elsewhere, falling back to `find` if `fd` is not\n  available. Fuzzy text selection is done with `fzy` by default: a fast,\n  well-behaved interactive filter.\n- It doesn't define default key mappings, allowing you to define your own\n  mappings that best fit your workflow and don't conflict with your other\n  plugins.\n\n## Installation\n\nTo use vim-picker you will first need a fuzzy selector such as [`fzy`][fzy]\n(recommended), [`pick`][pick], or [`selecta`][selecta] installed. See their\nrespective homepages for installation instructions.\n\nIf you already use a plugin manager, install vim-picker in the normal manner.\nOtherwise, the recommended plugin manager is [minpac]. Add the following to your\nvimrc (`$HOME/.vim/vimrc` for Vim and\n`${XDG_CONFIG_HOME:-$HOME/.config}/nvim/init.vim` for Neovim), restart Vim, and\nrun `:call minpac#update()`:\n\n```vim\ncall minpac#add('srstevenson/vim-picker')\n```\n\nIf you have Vim 7.4.1840 or newer, you can use the [native package\nsupport][packages] instead of a plugin manager by cloning vim-picker into a\ndirectory under [`packpath`][packpath]. For Vim:\n\n```sh\ngit clone https://github.com/srstevenson/vim-picker \\\n    ~/.vim/pack/plugins/start/vim-picker\n```\n\nFor Neovim:\n\n```sh\ngit clone https://github.com/srstevenson/vim-picker \\\n    ${XDG_DATA_HOME:-$HOME/.local/share}/nvim/site/pack/plugins/start/vim-picker\n```\n\n## Commands\n\nvim-picker provides the following commands:\n\n- `:PickerEdit`: Pick a file to edit in the current window. This takes a single\n  optional argument, which is the directory in which to run the file listing\n  tool. If not specified, this defaults to the current working directory.\n- `:PickerSplit`: Pick a file to edit in a new horizontal split. This takes an\n  optional directory argument in the same manner as `:PickerEdit`.\n- `:PickerTabedit`: Pick a file to edit in a new tab. This takes an optional\n  directory argument in the same manner as `:PickerEdit`.\n- `:PickerTabdrop`: Pick a file to edit in a new tab if no tab already contains\n  it or jump to the tab containing it. This takes an optional directory argument\n  in the same manner as `:PickerEdit`.\n- `:PickerVsplit`: Pick a file to edit in a new vertical split. This takes an\n  optional directory argument in the same manner as `:PickerEdit`.\n- `:PickerBuffer`: Pick a buffer to edit in the current window.\n- `:PickerBufferSplit`: Pick a buffer to edit in a new horizontal split.\n- `:PickerBufferVsplit`: Pick a buffer to edit in a new vertical split.\n- `:PickerTag`: Pick a tag to jump to in the current window.\n- `:PickerStag`: Pick a tag to jump to in a new horizontal split.\n- `:PickerBufferTag`: Pick a tag from the current buffer to jump to.\n- `:PickerHelp`: Pick a help tag to jump to in the current window.\n\n## Key mappings\n\nvim-picker defines the following [`\u003cPlug\u003e`][plug-mappings] mappings:\n\n- `\u003cPlug\u003e(PickerEdit)`: Execute `:PickerEdit`.\n- `\u003cPlug\u003e(PickerSplit)`: Execute `:PickerSplit`.\n- `\u003cPlug\u003e(PickerTabedit)`: Execute `:PickerTabedit`.\n- `\u003cPlug\u003e(PickerTabdrop)`: Execute `:PickerTabdrop`.\n- `\u003cPlug\u003e(PickerVsplit)`: Execute `:PickerVsplit`.\n- `\u003cPlug\u003e(PickerBuffer)`: Execute `:PickerBuffer`.\n- `\u003cPlug\u003e(PickerBufferSplit)`: Execute `:PickerBufferSplit`.\n- `\u003cPlug\u003e(PickerBufferVsplit)`: Execute `:PickerBufferVsplit`.\n- `\u003cPlug\u003e(PickerTag)`: Execute `:PickerTag`.\n- `\u003cPlug\u003e(PickerStag)`: Execute `:PickerStag`.\n- `\u003cPlug\u003e(PickerBufferTag)`: Execute `:PickerBufferTag`.\n- `\u003cPlug\u003e(PickerHelp)`: Execute `:PickerHelp`.\n\nThese are not mapped to key sequences, to allow you to choose those that best\nfit your workflow and don't conflict with other plugins you use. However, if you\nhave no preference, the following snippet maps the main mappings to mnemonic key\nsequences:\n\n```vim\nnmap \u003cunique\u003e \u003cleader\u003epe \u003cPlug\u003e(PickerEdit)\nnmap \u003cunique\u003e \u003cleader\u003eps \u003cPlug\u003e(PickerSplit)\nnmap \u003cunique\u003e \u003cleader\u003ept \u003cPlug\u003e(PickerTabedit)\nnmap \u003cunique\u003e \u003cleader\u003epd \u003cPlug\u003e(PickerTabdrop)\nnmap \u003cunique\u003e \u003cleader\u003epv \u003cPlug\u003e(PickerVsplit)\nnmap \u003cunique\u003e \u003cleader\u003epb \u003cPlug\u003e(PickerBuffer)\nnmap \u003cunique\u003e \u003cleader\u003ep] \u003cPlug\u003e(PickerTag)\nnmap \u003cunique\u003e \u003cleader\u003epw \u003cPlug\u003e(PickerStag)\nnmap \u003cunique\u003e \u003cleader\u003epo \u003cPlug\u003e(PickerBufferTag)\nnmap \u003cunique\u003e \u003cleader\u003eph \u003cPlug\u003e(PickerHelp)\n```\n\n## Configuration\n\nBy default, vim-picker uses Git to list files in Git repositories, and `fd`\noutside of Git repositories, falling back to `find` if `fd` is not available. To\nuse an alternative method of listing files, for example because you want to\ncustomise the flags passed to Git, because you use a different version control\nsystem, or because you want to use an alternative to `fd` or `find`, a custom\nfile listing tool can be used.\n\nTo use a custom file listing tool, set `g:picker_custom_find_executable` and\n`g:picker_custom_find_flags` in your vimrc. For example, to use\n[`ripgrep`][ripgrep] set:\n\n```vim\nlet g:picker_custom_find_executable = 'rg'\nlet g:picker_custom_find_flags = '--color never --files'\n```\n\nIf `g:picker_custom_find_executable` is set, and the executable it references is\nfound, it will always be used in place of Git, `fd`, or `find`. Therefore, you\nmay want to make `g:picker_custom_find_executable` a wrapper script that\nimplements your own checks and fallbacks: for example using `hg` in Mercurial\nrepositories, `ripgrep` elsewhere, and falling back to `find` if `ripgrep` is\nnot installed.\n\n`fzy` is used as the default fuzzy selector. To use an alternative selector, set\n`g:picker_selector_executable` and `g:picker_selector_flags` in your vimrc. For\nexample, to use [`pick`][pick] set:\n\n```vim\nlet g:picker_selector_executable = 'pick'\nlet g:picker_selector_flags = ''\n```\n\nvim-picker has been tested with `fzy`, `pick`, and `selecta`, but any\nwell-behaved command line filter should work. If your version of Vim does not\ncontain an embedded terminal emulator, but you run Vim within [tmux], setting\n`g:picker_selector_executable` to the [`fzy-tmux`][fzy-tmux] script distributed\nwith `fzy` will open the fuzzy selector in a new tmux pane below Vim, providing\nan interface similar to using the embedded terminal emulator of Neovim or Vim\n8.1.\n\nBy default, when an embedded terminal emulator is available vim-picker will run\nthe fuzzy selector in a full width split at the bottom of the window, using\n[`:botright`][botright]. You can change this by setting `g:picker_split` in your\nvimrc. For example, to open a full width split at the top of the window, set:\n\n```vim\nlet g:picker_split = 'topleft'\n```\n\nSee [`opening-window`][opening-window] for other valid values.\n\nTo specify the height of the window in which the fuzzy selector is opened, set\n`g:picker_height` in your vimrc. The default is 10 lines:\n\n```vim\nlet g:picker_height = 10\n```\n\n## Custom commands\n\nFor use cases not covered by the built-in functions, vim-picker also exposes\nlower level functions that allow you to specify any shell command to generate\nselection candidates with, combined with any Vim command to run on the output.\nThese are `picker#String()` and `picker#File()`:\n\n```vim\ncall picker#String({shell_command}, {vim_command})\ncall picker#File({shell_command}, {vim_command}, ...)\n```\n\nThese take the following arguments:\n\n1. A shell command that generates a newline-separated list of candidates to pass\n   to the fuzzy selector. The shell command can utilise pipes to chain commands\n   together.\n2. A Vim command, such as `edit` or `tjump`. The item selected in the fuzzy\n   selector is passed to this Vim command as a single argument.\n\nThe two functions are equivalent, except that `picker#File()` escapes the user's\nselection for use as a filename (for passing to Vim commands such as `:edit`)\nwhereas `picker#String()` does not.\n\nFor example, to edit a Markdown file stored in `~/notes` in a new tab, use:\n\n```vim\ncall picker#File('find ~/notes -name \"*.md\"', 'tabe')\n```\n\nIn addition to `shell_command` and `vim_command`, `picker#File` accepts a third\nargument which is a dictionary controlling its behaviour.\n\nIt may contain the following keys:\n\n- `cwd` controls where `shell_command` is run.\n- `line_handler` must be the name of a function taking a single argument, and\n  must return a dictionary. This function will be called for every user\n  selection and allows the user to do some preprocessing, for example to strip\n  extra information or to extract line and column information. The returned\n  dictionary can have the following keys:\n  - `filename`: the name of the file to open (mandatory).\n  - `line`: the line to go to in the file (optional).\n  - `column`: the column to go to in the line (optional).\n\nFor example, to use `ripgrep` to search for a pattern in files:\n\n```vim\nfunction! PickerRgLineHandler(selection) abort\n    let parts = split(a:selection, ':')\n    return {'filename': parts[0], 'line': parts[1], 'column': parts[2]}\nendfunction\n\ncommand! -nargs=? PickerRg\n    \\ call picker#File('rg --color never --line-number --column '.shellescape(\u003cq-args\u003e), \"edit\", {'line_handler': 'PickerRgLineHandler'})\n```\n\nUsing `:PickerRg \u003cpattern\u003e` will search for the specified pattern and when a\nmatch is selected the file will be opened at the line and column of the match.\n\n## Copyright\n\nCopyright © Scott Stevenson.\n\nvim-picker is distributed under the terms of the [ISC license].\n\n[botright]: https://neovim.io/doc/user/windows.html#:botright\n[command-t]: https://github.com/wincent/command-t\n[ctrlp.vim]: https://github.com/ctrlpvim/ctrlp.vim\n[fd]: https://github.com/sharkdp/fd\n[fzy-tmux]: https://github.com/jhawthorn/fzy/blob/master/contrib/fzy-tmux\n[fzy]: https://github.com/jhawthorn/fzy\n[isc license]: https://opensource.org/licenses/ISC\n[minpac]: https://github.com/k-takata/minpac\n[neovim]: https://neovim.io/\n[nvim-terminal]: https://neovim.io/doc/user/nvim_terminal_emulator.html\n[opening-window]: https://neovim.io/doc/user/windows.html#opening-window\n[packages]: https://neovim.io/doc/user/repeat.html#packages\n[packpath]: https://neovim.io/doc/user/options.html#'packpath'\n[pick]: https://github.com/mptre/pick\n[plug-mappings]: https://neovim.io/doc/user/map.html#%3CPlug%3E\n[ripgrep]: https://github.com/BurntSushi/ripgrep\n[selecta]: https://github.com/garybernhardt/selecta\n[telescope]: https://github.com/nvim-telescope/telescope.nvim\n[tmux]: https://tmux.github.io/\n[vim-picker]: https://github.com/srstevenson/vim-picker\n[vim-terminal]: https://vimhelp.org/terminal.txt.html\n[vim]: http://www.vim.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrstevenson%2Fvim-picker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsrstevenson%2Fvim-picker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsrstevenson%2Fvim-picker/lists"}