{"id":13898754,"url":"https://github.com/samoshkin/vim-find-files","last_synced_at":"2025-06-17T21:42:50.527Z","repository":{"id":140675173,"uuid":"179501615","full_name":"samoshkin/vim-find-files","owner":"samoshkin","description":":mag_right: Search for files and show results in a quickfix list, new buffer, or populate the argument list.","archived":false,"fork":false,"pushed_at":"2020-07-27T05:36:35.000Z","size":16,"stargazers_count":29,"open_issues_count":3,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-17T02:49:41.552Z","etag":null,"topics":["find","search","vim","vim-plugins"],"latest_commit_sha":null,"homepage":"","language":"Vim script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samoshkin.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2019-04-04T13:20:37.000Z","updated_at":"2025-01-30T23:25:11.000Z","dependencies_parsed_at":"2024-02-28T06:13:15.987Z","dependency_job_id":"ed4505a6-0043-4813-ae08-974ea31394eb","html_url":"https://github.com/samoshkin/vim-find-files","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/samoshkin/vim-find-files","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Fvim-find-files","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Fvim-find-files/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Fvim-find-files/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Fvim-find-files/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samoshkin","download_url":"https://codeload.github.com/samoshkin/vim-find-files/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samoshkin%2Fvim-find-files/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260445454,"owners_count":23010385,"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":["find","search","vim","vim-plugins"],"created_at":"2024-08-06T18:04:26.501Z","updated_at":"2025-06-17T21:42:45.512Z","avatar_url":"https://github.com/samoshkin.png","language":"Vim script","funding_links":[],"categories":["Vim Script"],"sub_categories":[],"readme":"# vim-find-files\n\nSearch for files and show results in a quickfix list, a new buffer, or populate the Vim's argument list.\n\n## Demo\nSee this [Vim Universe](https://vimeo.com/328924428) screencast on Vimeo, that shows the plugin usage. If you want to skip introduction and rationale behind this plugin, use this [time code](https://vimeo.com/328924428#t=3m0s).\n\n[![Plugin demo](https://i.vimeocdn.com/video/773584357.webp?mw=960\u0026mh=540)](https://vimeo.com/328924428)\n\n\n## Overview\n`vim-find-files` plugin allows you to search for files in a directory hierarchy. This is same to using GNU `find` in a shell, but now you don't have to leave Vim.\n\nOut of the box, Vim has `grepprg` setting and accompanying `:grep` command to search for a text matching a pattern in multiple files. `vim-find-files` plugin brings `findprg` setting and `:Find` command to search for file names matching a pattern.\n\n\n**Features**:\n- Show matching files in different views: quickfix list (default), new buffer, argument list, custom user-defined view. Buffer option is useful, when you want to further edit the file list.\n- Convert between views. For example, you can start with a quickfix list to review matches, convert to a buffer to remove some files from a list, and finally convert to the argument list to execute `:grep` command next against it.\n- Open and preview files from the file list buffer using predefined mappings.\n- Search relative to the `cwd` or to the current file's directory.\n- Filter any quickfix list to keep unique files only. See files with at least one match. Useful when you run `:grep` command and want to see list of matched files, instead of individual matches. This is similar to running `grep --files-with-matches` in a shell.\n\n## Example\n\nUse your favorite Vim plugin manager to install the plugin.\n\nSpecify find backend in your `vimrc`. Either use GNU `find`, or some advanced tools like [fd](https://github.com/sharkdp/fd). Make sure to define `$*` and `$d` placeholders for search pattern and starting directory respectively.\n```vim\nlet g:find_files_findprg = 'find $d ! -type d $*'\n\n\" Or Use sharkdp/fd as a backend\n\" let g:find_files_findprg = 'fd --hidden $* $d'\n```\nUse `:Find {args}` command to search for files and show them in a quickfix list. Note, that `args` value depends on the selected `findprg` backend. For example, `:Find -name *.vim` is the valid command when using GNU `find`, whereas simple `:Find .vim` is the valid choice for [fd](https://github.com/sharkdp/fd). The rule of thumb is to respect underlying find program interface.\n\nUse `:FindA {args}` or `:FindB {args}` command variants to show results in the argument list or in a new buffer respectively.\n\nUse one of `:Buf2Qf`, `:Buf2Args`, `:Qf2Buf`, `:Qf2Args`, `:Args2Qf`, `:Args2Buf` commands to convert between views on the fly: `quickfix \u003c---\u003e buffer \u003c---\u003e args list`.\n\n\n## Features and customization\n\n### Find command\n\nBy default following commands are exported:\n- `:Find {args}`, search for files and show results in a quickfix list\n- `:FindA {args}`, populate Vim's argument list with the list of matched files\n- `:FindB {args}`, show search results in a new buffer\n\nIf you don't like the default command name, you can override it. In the example below, `Search`, `SearchA` and `SearchB` commands would be exported respectively.\n```vim\nlet g:find_files_command_name = 'Search'\n```\nIf you don't want any commands being exported at all, set the command name to an empty string.\n\n```vim\nlet g:find_files_command_name = ''\n```\n\nIn the latter case, you can define your own commands by referring to `find_files#execute()` function.\n\n```vim\ncommand! -nargs=* -bang MyCommand :call find_files#execute(\u003cq-args\u003e, 'qf', \u003cbang\u003e0)\n```\n\nSignature of the `find_files#execute(args, view, is_relative)` function:\n\n1. `args`, arguments passed to the `findprg` backend\n2. `view`, how to show search results. Valid values: `qf`, `buf`, `args`, or user-defined `funcref`.\n2. `is_relative`, whether search should be relative to the current file's directory or to the `cwd`.\n\n\n### File list buffer\nWhen you're using `:FindB` command, search results are shown in a new buffer. \n\nBy default, `enew` command is used to open the buffer. If you want to open a buffer in a new split, or in a new tab:\n\n```vim\n\" 'enew'(default), 'vnew', 'new' or 'tabnew'\nlet g:find_files_buf_command = \"vnew\"\n```\n\nExtra buffer-local mappings are defined:\n\n- `o`, open file under the cursor in the same window\n- `O`, open file under the cursor in a new split and focus it\n- `p`, preview file under the cursor in a new split, but keep focus in the file list buffer\n- `q`, close buffer with search results and any preview windows\n\nYou can override mappings, if they hide default Vim's behavior:\n\n```vim\nlet g:find_files_buf_mappings = {\n  \\ 'open': '\u003cCR\u003e',\n  \\ 'preview': '\u003cF2\u003e',\n  \\ }\n```\n\nOr you can disable mappings completely:\n\n```vim\nlet g:find_files_define_mappings = 0\n```\n\nWhen file is opened with `O` or `p` shortcuts, vertical split is used by default. You can override this behavior:\n\n```vim\n\" 'vsplit'(default) or 'split'\nlet g:find_files_buf_preview_command = \"split\"\n```\n\nBy default, the buffer has following settings: `nowrap`, `nospell`, `nofoldenable`, `norelativenumber`. Note, that the buffer has dedicated `filetype=findfiles`, so you can apply own buffer-local customizations using `FileType` auto command:\n \n```vim\naugroup my_find_files_customization\n  au!\n\n  \" Custom mappings\n  au FileType findfiles nnoremap \u003csilent\u003e \u003cbuffer\u003e \u003cCR\u003e gf\n\n  \" Custom settings\n  au FileType findfiles setlocal wrap\naugroup END\n```\n\n### Convert between views\n\nYou're not limited to a single view only. You can convert between views back and forth as you go.\n\nThe example workflow can look as follows:\n\n1. Run `:Find {args}` command. Review search results in a quickfix list.\n2. Run `:Qf2Buf` command. Open in a new buffer. Remove some files from the list.\n3. Run `:Buf2Args` command. Populate Vim's argument list with the filtered files list from the buffer.\n4. Run `:grep {pattern} ##` to search for text matching a pattern, but only within a files from the argument list.\n\nWorkflow #2:\n\n1. Run `:gpep {pattern}` command. Review individual matches using a quickfix list.\n2. Run `:Qf2Buf` command. Show only matched unique files in a new buffer.\n\nFollowing commands are exported. Compose them as you need:\n- `Buf2Args`, populate the arguments list with files from the buffer\n- `Buf2Qf`, populate the quickfix list with files from the buffer\n- `Qf2Buf`, get unique files from the quickfix list and show in a new buffer\n- `Qf2Args`, populate the arguments list with unique files from the quickfix list\n- `Args2Qf`, convert arguments list to quickfix list\n- `Args2Buf`, get files from the arguments list and show in a new buffer\n\n\n### Search relative to current file\n\nBy default, when you run `:Find` command, search is relative to current `cwd`. You can suffix the command with a bang (`!`) to force search relative to the directory of the current file. Useful, when you want to limit a search to directory of the current file or any nested directories.\n\n```vim\n: Find! {pattern}\n```\n\n### Keep files only in a quickfix list\n\nYou can process any quickfix list to keep only files with at least one match, instead of focusing on individual matches. This is somewhat similar to running `grep --files-with-matches` in a shell.\n\nRun `:FilesOnly` command, which is available in the quickfix window only. It will create a new quickfix list. If you want to get back to the original list, use `:colder` Vim command.\n\n\n### Show search results in a custom view\n \nIf you're not satisfied with predefined views (quickfix, buffer, arguments list) and looking for a custom way to render search results, you can provide your own implementation.\n\nFirst, define custom function responsible for showing search results.\n\n```vim\n\" Arguments:\n\" - list of files\n\" - underlying 'find' command that yield search results\nfunction s:show_files(files, command)\n  \" Your own implementation\n  \" Show files however you like\nendfunction\n```\n\nSecond, declare custom `Find` command, and pass the function above as a callback to `find_files#execute()` call.\n```vim\n\" Define custom 'Find' command\ncommand! -nargs=* -bang FindX :call find_files#execute(\u003cq-args\u003e, function('s:show_files'), \u003cbang\u003e0)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamoshkin%2Fvim-find-files","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamoshkin%2Fvim-find-files","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamoshkin%2Fvim-find-files/lists"}