Periscope is a VSCode extension that supercharges your ability to search workspace contents using ripgrep, providing an intuitive interface with real-time previews of search results.
Inspired by nvim's telescope
ripgrep
for lightning-fast search capabilities.<super> + p
to invoke the periscope.search
command. You can also access it via the command palette (Ctrl+Shift+P
or Cmd+Shift+P
) and search for periscope.Enter
to open the highlighted file or Esc
to cancel and return to your work.For optimal performance, ensure that the VSCode configuration Editor: Enable Preview is enabled. This allows files to be previewed before opening them completely.
periscope.search
to have it automatically used as the initial query.rgQueryParams
: Create shortcuts for common ripgrep search queries via regex matching against your current query. This provides a way to map your query to ripgrep parameters via capture groups in the regex.rgOptions
: Additional options to pass to the 'rg' command, you can view all options in your terminal via 'rg --help'.rgGlobExcludes
: Additional glob paths to exclude from the 'rg' search, eg: '/dist/'.rgPath
: Optional path to the rg
binary. If not specified, the ripgrep bundled with vscode will be used.addSrcPaths
: Additional source paths to include in the rg search. You may want to add this as a workspace specific setting.rgMenuActions
: Create menu items which can be selected prior to any query, these items will be added to the ripgrep command to generate the results. Eg: Add { "label": "JS/TS", "value": "--type-add 'jsts:*.{js|ts|tsx|jsx}' -t jsts" },
as a menu option to only show js & ts files in the results.rgQueryParams
: Match ripgrep parameters from the input query directly. E.g: { "regex": \"^(.+) -t ?(\\w+)$\", "param": \"-t $1\" },
will translate the query hello -t rust
to rg 'hello' -t rust
to enable a filetype filter.rgQueryParamsShowTitle
: When a ripgrep parameter match from the list in rgQueryParams
, the quick pick will show the matched result as a preview in the title bar.startFolderDisplayIndex
: The folder index to display in the results before '...'.startFolderDisplayDepth
: The folder depth to display in the results before '...'.endFolderDisplayDepth
: The folder depth to display in the results after '...'.alwaysShowRgMenuActions
: If true, then open rg menu actions every time the search is invoked.showPreviousResultsWhenNoMatches
: If true, when there are no matches for the current query, the previous results will still be shown.gotoRgMenuActionsPrefix
: If the query starts with this prefix, then open rg menu actions.enableGotoNativeSearch
: If true, then swap to native vscode search if the custom suffix is entered using the current query.gotoNativeSearchSuffix
: If the query ends with this suffix, then swap to the native search with the query applied.peekBorderColor
: Change the peek color ('white', '#FFF' '#FFFFFFF', 'rgb(255,255,255)','rgba(255, 255, 255. 0.5) )peekBorderWidth
: Change the peek border width (px)peekBorderStyle
: Change the peek border style (solid, dashed, inset, double, groove, outset, ridge)Detailed examples for setting up advanced search parameters and UI customization are provided below to help you tailor Periscope to fit your workflow.
Create shortcuts for common ripgrep search queries via regex matching against your current query. This provides a way to map your query to ripgrep parameters via capture groups in the regex.
Add the following to your settings.json
:
"periscope.rgQueryParams": [
{
// filter the results to a folder
// Query: "redis -m module1"
// After: "rg 'redis' -g '**/*module1*/**'"
"regex": "^(.+) -m ([\\w-_]+)$",
"param": "-g '**/*$1*/**' -g '!**/node_modules/**'"
},
{
// filter the results to a folder and filetype
// Query: "redis -m module1 yaml"
// After: "rg 'redis' -g '**/*module1*/**/*.yaml'"
"regex": "^(.+) -m ([\\w-_]+) ([\\w]+)$",
"param": "-g '**/*$1*/**/*.$2'"
},
{
// filter the results that match a glob
// Query: "redis -g *module"
// After: "rg 'redis' -g '*module'"
"regex": "^(.+) -g (.+)$",
"param": "-g '$1'"
},
{
// filter the results to rg filetypes
// Query: "redis -t yaml"
// After: "rg 'redis' -t yaml"
"regex": "^(.+) -t ?(\\w+)$",
"param": "-t $1"
},
{
// filter the results that match a file extension through a glob
// Query: redis *.rs => rg 'redis' -g '*.rs'
"regex": "^(.+) \\*\\.(\\w+)$",
"param": "-g '*.$1'"
}
],
Open the result preview in a horizontal split.
Add a keybinding (keybindings.json
):
{
"key": "ctrl+v",
"command": "periscope.openInHorizontalSplit",
"when": "periscopeActive"
}
This extension contributes the following settings:
periscope.search
: Enable Periscope Searchperiscope.openInHorizontalSplit
: Open the result preview in a horizontal splitFor common issues and troubleshooting guidance, please visit the Issues section of our GitHub repository. If you encounter a problem not covered there, feel free to open a new issue.
Interested in contributing to Periscope? We welcome contributions of all forms. Please visit our Contributions Page for more information on how to get involved.
For support with using Periscope or to provide feedback, please open an issue in our GitHub repository.