PSFavorite

This module allows you to mark commands as favorites. Your favorite commands will appear as suggestions in the PSReadLine Predictor Views.

Favorites do not replace history, they complement it. The history tracks everything you've done, and favorites track the things that you've deemed important.

---

📘 Usage

Write a command and press Ctrl + Shift + * to mark it as favorite.

Note: Add a helpful comment to describe the command for future reference.

Alternatively, use the Add-PSFavorite cmdlet

PS C:\> "Get-Command | Get-Random | Get-Help    # Get help about a random command" | Add-PSFavorite

Note: Remember to wrap the expressions in quotes!

Your favorite commands will start appearing as suggestions in the PSReadLine Predictor View.

See the Cmdlets section below for more details on how to manage your favorites list.

🌟 Favorites File

The favorites file is where your favorite commands are stored. By default, it is located at:

• Windows: $Env:LOCALAPPDATA\PSFavorite\Favorites.txt
• Linux/macOS: $HOME/.local/share/PSFavorite/Favorites.txt

You can get the current path to the favorites file using the Get-PSFavoritePath cmdlet:

Get-PSFavoritePath

Favorites are stored in a simple text format, one command per line along with an optional comment description.

Get-ChildItem -Filter *.md    # List all Markdown files in the current directory
Get-Process | Where-Object CPU -gt 25 # Get processes consuming more than 25 CPU units
git reset --hard HEAD~1    # Undo the last Git commit, discarding changes

📜 Cmdlets

• Add-PSFavorite - Add a command to your favorites list.
• Get-PSFavorite - Get the list of your favorite commands.
• Remove-PSFavorite - Remove a command from your favorites list.
• Get-PSFavoritePath - Get the path to the favorites file.
• Optimize-PSFavorite - Optimize the favorites file by removing duplicates and sorting entries.
• Initialize-PSFavorite - Initialize the favorites file and directory.

Tip

Remember, Get-Help is your friend! Use it to learn more about each cmdlet and its parameters.

---

📄 Requirements

• PowerShell v7.2.0 or higher
• PSReadLine v2.2.2 or higher

PSReadLine should be installed by default in PowerShell 7+, but if not, you can install it using:

Install-Module -Name PSReadLine

PSReadLine must allow plugins as a -PredictionSource. (i.e. Plugin or HistoryAndPlugin)

Set-PSReadLineOption -PredictionSource HistoryAndPlugin

To enable the List view:

Set-PSReadLineOption -PredictionViewStyle ListView

📦 Installation

1. Install the Module

Install-Module -Name PSFavorite

2. Import the Module

Import-Module -Name PSFavorite

3. Initialize the Favorites File

Initialize-PSFavorite # Initialize PSFavorite with the default configuration

or alternatively, to configure the path and keybind:

Initialize-PSFavorite -Path "C:\MyFavorites.txt" -KeyBind "Ctrl+Shift+F"

Note

Add this to your $PROFILE if you wish to enable this for every session.

🪓 Uninstallation

1. Close all PowerShell instances
2. Launch a PowerShell session with no profile. pwsh -NoProfile
3. Uninstall the Module. Uninstall-Module -Name PSFavorite -Force
4. Close PowerShell

---

💽 Development

📜 Scripts

• Build.ps1 - Builds the C# predictor and copies the DLL to the Module directory.

./Build.ps1 -Configuration Release

Warning

If the dll is locked by PowerShell, you may need to kill all PowerShell processes that have it loaded and run the build script again. This is always a pain during development, but I haven't found a good workaround for it yet.

🧪 Testing

This module uses Pester for testing the PowerShell Module. To test the module, first build it and then run the following command.

./Build.ps1 # To build the module and predictor DLL
Invoke-Pester -Path ./Module/Tests -Verbose # Run all Pester tests in the Module/Tests directory

The C# predictor includes a small xUnit test project. To run the .NET tests (after restore) run:

dotnet test # Run all .NET tests in the solution

🚢 Publishing

Version

Ensure the ModuleVersion in Module/PSFavorite.psd1 and <Version> in Predictor/PSFavoritePredictor.csproj is updated before creating a release.

Create a git tag for the release and push it to GitHub.

git tag -a v1.0.0 -m "Release version 1.0.0"
git push --tags

Publish to PowerShell Gallery

To publish the module to the PowerShell Gallery, you can use the Publish-Module cmdlet using an API key from your PowerShell Gallery account.

Publish-Module -Path ./Module -NuGetApiKey YOUR_API_KEY

I did consider GitHub Actions for CI/CD, but since this is a personal project and I don't plan on frequent releases, not to mention all the horror-stories, I decided to keep it simple with manual publishing for now.

📕 Reference

• https://learn.microsoft.com/en-us/powershell/scripting/dev-cross-plat/create-cmdline-predictor

---

📃 License

This project is licensed under the MIT License. Please read the LICENSE for more details.