Home

Awesome

PSFzf

PowerShell Gallery Version PowerShell Gallery Version PowerShell Gallery Downloads Build status MIT licensed

PSFzf is a PowerShell module that wraps fzf, a fuzzy file finder for the command line.

keyboard shortcut demonstration

Usage

To change to a user selected directory:

Get-ChildItem . -Recurse -Attributes Directory | Invoke-Fzf | Set-Location

To edit a file:

Get-ChildItem . -Recurse -Attributes !Directory | Invoke-Fzf | % { notepad $_ }

For day-to-day usage, see the helper functions included with this module.

PSReadline Integration

Select Current Provider Path (default chord: <kbd>Ctrl+t</kbd>)

Press <kbd>Ctrl+t</kbd> to start PSFzf to select provider paths. PSFzf will parse the current token and use that as the starting path to search from. If current token is empty, or the token isn't a valid path, PSFzf will search below the current working directory.

Multiple items can be selected. If more than one is selected by the user, the results are returned as a comma separated list. Results are properly quoted if they contain whitespace.

Reverse Search Through PSReadline History (default chord: <kbd>Ctrl+r</kbd>)

Press <kbd>Ctrl+r</kbd> to start PSFzf to select a command in the command history saved by PSReadline. PSFzf will insert the command into the current line, but it will not execute the command.

PSFzf does not override <kbd>Ctrl+r</kbd> by default. To confirm that you want to override PSReadline's chord binding, use the Set-PsFzfOption command:

# replace 'Ctrl+t' and 'Ctrl+r' with your preferred bindings:
Set-PsFzfOption -PSReadlineChordProvider 'Ctrl+t' -PSReadlineChordReverseHistory 'Ctrl+r'

Set-Location Based on Selected Directory (default chord: <kbd>Alt+c</kbd>)

Press <kbd>Alt+c</kbd> to start PSFzf to select a directory. By default, Set-Location will be called with the selected directory. You can override the default command with the following code in our $PROFILE:

# example command - use $Location with a different command:
$commandOverride = [ScriptBlock]{ param($Location) Write-Host $Location }
# pass your override to PSFzf:
Set-PsFzfOption -AltCCommand $commandOverride

Search Through Command Line Arguments in PSReadline History (default chord: <kbd>Alt+a</kbd>)

Press <kbd>Alt+a</kbd> to start PSFzf to select command line arguments used in PSReadline history. The picked argument will be inserted in the current line. The line that would result from the selection is shown in the preview window.

Tab Expansion

PSFzf can replace the standard tab completion:

Set-PSReadLineKeyHandler -Key Tab -ScriptBlock { Invoke-FzfTabCompletion }

To activate continuous completion, press the directory separator character to complete the current selection and start tab completion for the next part of the container path.

PSFzf supports specialized tab expansion with a small set of commands. After typing the default trigger command, which defaults to "**", and press <kbd>Tab</kbd>, PsFzf tab expansion will provide selectable list of options.

The following commands are supported:

CommandNotes
gitUses posh-git for providing tab completion options. Requires at least version 1.0.0 Beta 4.
Get-Service, Start-Service, Stop-ServiceAllows the user to select between the installed services.
Get-Process, Start-ProcessAllows the user to select between running processes.

To override the trigger command, set FZF_COMPLETION_TRIGGER to your preferred trigger sequence.

Use the following command to enable tab expansion:

Set-PsFzfOption -TabExpansion

Using within a Pipeline

Invoke-Fzf works with input from a pipeline. You can use it in the middle of a pipeline, or as part of an expression.

Set-Location (Get-ChildItem . -Recurse | ? { $_.PSIsContainer } | Invoke-Fzf) # This works as of version 2.2.8
Get-ChildItem . -Recurse | ? { $_.PSIsContainer } | Invoke-Fzf | Set-Location

Overriding Behavior

PsFzf supports overriding behavior by setting these fzf environment variables:

Env Var NameDescription
_PSFZF_FZF_DEFAULT_OPTSIf this environment variable is set, then FZF_DEFAULT_OPTS is temporarily set with the contents. This allows the user to have different default options for PSFZF and fzf.
FZF_DEFAULT_COMMANDThe command specified in this environment variable will override the default command when PSFZF detects that the current location is a file system provider.
FZF_CTRL_T_COMMANDThe command specified in this environment variable will be used when <kbd>Ctrl+t</kbd> is pressed by the user.
FZF_ALT_C_COMMANDThe command specified in this environment variable will be used when <kbd>Alt+c</kbd> is pressed by the user.
PSFZF_EDITOR_OPTIONSContains options passed to the editor application used in the Invoke-FuzzyEdit() function

Helper Functions

In addition to its core function Invoke-Fzf, PSFzf includes a set of useful functions and aliases. The aliases are not installed by default. To enable aliases, use Set-PSFzfOption's -EnableAlias* options.

FunctionAliasDescription
Invoke-FuzzyEditfeStarts an editor for the selected files in the fuzzy finder.
Invoke-FuzzyFasdffStarts fzf with input from the files saved in fasd(non-Windows) or fasdr (Windows) and sets the current location.
Invoke-FuzzyZLocationfzStarts fzf with input from the history of ZLocation and sets the current location.
Invoke-FuzzyGitStatusfgsStarts fzf with input from output of the git status function.
Invoke-FuzzyHistoryfhRerun a previous command from history based on the user's selection in fzf.
Invoke-FuzzyKillProcessfkillRuns Stop-Process on processes selected by the user in fzf.
Invoke-FuzzySetLocationfdSets the current location from the user's selection in fzf.
Invoke-FuzzyScoopfsStarts fzf on Scoop applications list.
Invoke-PsFzfRipgrepN/AUses Ripgrep and Fzf to interactively search files.
Set-LocationFuzzyEverythingcdeSets the current location based on the Everything database.

Prerequisites

Follow the installation instructions for fzf before installing PSFzf. PSFzf will run Get-Command to find fzf in your path.

Windows

The latest version of fzf is available via Chocolatey, or you can download the fzf binary and place it in your path. Run Get-Command fzf*.exe to verify that PowerShell can find the executable.

PSFzf has been tested under PowerShell 5.0, 6.0, and 7.0.

MacOS

Use Homebrew or download the binary and place it in your path. Run Get-Command fzf* to verify that PowerShell can find the executable.

PSFzf has been tested under PowerShell 6.0 and 7.0.

Linux

PSFzf has been tested under PowerShell 6.0 and 7.0 in the Windows Subsystem for Linux.

Installation

PSFzf is available on the PowerShell Gallery and Scoop. PSReadline should be imported before PSFzf as PSFzf registers PSReadline key handlers listed in the PSReadline integration section.

Helper Function Requirements