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
- Fast Search: Utilizes
ripgrepfor lightning-fast search capabilities. - Real-Time Preview: See preview of files right in the search pane as you navigate through search results.
- Customizable: Extensive configuration options to tailor search behavior and UI to your needs.
- Invoke Search: Assign a keybinding such as
<super> + pto invoke theperiscope.searchcommand. You can also access it via the command palette (Ctrl+Shift+PorCmd+Shift+P) and search for periscope. - Search and Preview: Enter your query to see the search results dynamically. Navigate through results to preview files directly in the editor.
- Open or Cancel: Press
Enterto open the highlighted file orEscto 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.
- Search with Regex: Use regex in your search query to find specific patterns in your codebase.
- Selected Text Search: Highlight text in the editor and invoke
periscope.searchto have it automatically used as the initial query. - Raw Queries: Enclosing your
search_termin quotes will allow additional ripgrep parameters to be passed through. eg:"foobar" -t jswill search forfoobarin js files. - Utilise
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 for faster lookups.
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 thergbinary. 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 queryhello -t rusttorg 'hello' -t rustto enable a filetype filter.rgQueryParamsShowTitle: When a ripgrep parameter match from the list inrgQueryParams, the quick pick will show the matched result as a preview in the title bar.showWorkspaceFolderInFilePath: Include workspace folder name in the folder depth display.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 split.
For 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.