From cc0952c41ee15e73d8421c840ed23e416fb39bee Mon Sep 17 00:00:00 2001 From: stijn Date: Wed, 21 Apr 2021 09:55:28 +0200 Subject: [PATCH 1/3] Fix some grammar and style issues in the README --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index d0b123f..1426671 100644 --- a/README.md +++ b/README.md @@ -5,8 +5,8 @@ ZLocation [![Join the chat at https://gitter.im/vors/ZLocation](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/vors/ZLocation?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -Tracks your most used directories, based on number of previously run commands. -After a short learning phase, `z` will take you to the most popular directory that matches all of the regular expressions given on the command line. +Tracks your most used directories, based on the number of commands ran previously. +After a short learning phase, `z` will take you to the most popular directory that matches all of the regular expressions given on the command line. You can use **Tab-Completion / Intellisense** to pick directories that are not the first choice. ZLocation is the successor of [Jump-Location](https://github.com/tkellogg/Jump-Location). @@ -16,10 +16,10 @@ Usage ----- ZLocation keeps track of your `$pwd` (current folder). -Once visited, folder become known to ZLocation. +Once visited, the folder becomes known to ZLocation. You can `cd` with just a hint of the path! -The full command name is `Invoke-ZLocation`, but in examples I use alias `z`. +The full command name is `Invoke-ZLocation`, but in the examples I use the alias `z`. It's all about navigation speed, isn't it? ``` @@ -32,7 +32,7 @@ PS C:\dev\ZLocation\ZLocation.Tests> ### List known locations -`z` without arguments will list all the known locations and their weights (short-cut for `Get-ZLocation`) +`z` without arguments will list all the known locations and their weights (shortcut for `Get-ZLocation`) To see all locations matched to a query `foo` use `z -l foo`. @@ -79,7 +79,7 @@ Install-Module ZLocation -Scope CurrentUser ``` Make sure to **include ZLocation import in your `$PROFILE`**. -It intentionally doesn't alternate `$PROFILE` automatically on installation. +It intentionally doesn't alter `$PROFILE` automatically on installation. This one-liner installs ZLocation, imports it and adds it to a profile. @@ -94,9 +94,9 @@ Write-Host -Foreground Green "`n[ZLocation] knows about $((Get-ZLocation).Keys.C ### Note -ZLocation alternates your prompt function to track the location. Meaning if you use this module with other modules that modifies your prompt function (e.g. such as `posh-git`), then you'd need to adjust your [Powershell profile file](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7). The statement `Import-Module ZLocation` needs to be placed **after** the other module imports that modifies your prompt function. +ZLocation alters your prompt function to track the location. Meaning if you use this module with other modules that modify your prompt function (e.g. `posh-git`), then you'd need to adjust your [Powershell profile file](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7). The statement `Import-Module ZLocation` needs to be placed **after** the other module imports that modify your prompt function. -You can open up `profile.ps1` through using any of the below commands: +You can open `profile.ps1` using any of the below commands: ```powershell notepad $PROFILE.CurrentUserAllHosts @@ -104,7 +104,7 @@ notepad $env:USERPROFILE\Documents\WindowsPowerShell\profile.ps1 notepad $Home\Documents\WindowsPowerShell\profile.ps1 ``` -Alternatively, type up the below in your file explorer, and then edit the `profile.ps1` file with an editor of your choice: +Alternatively, type the below in your file explorer, and then edit the `profile.ps1` file with an editor of your choice: ``` %USERPROFILE%\Documents\WindowsPowerShell From f0376c9ecbd33cd8d218303ad9f0f404ffc2b8aa Mon Sep 17 00:00:00 2001 From: stijn Date: Wed, 21 Apr 2021 10:13:12 +0200 Subject: [PATCH 2/3] Fix instructions regarding profile in README Mention the directory needs to exist otherwise users are greeted with rather meaningless 'The system cannot find the path specified.' errors. Remove the instructions which hardcode the profile directory because they are incorrect for PowerShell Core and teaching users to use $PROFILE is better anyway. Mention the default directory used for PowerShell Core as well to make sure users know there are multiple locations. --- README.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 1426671..c1f9a65 100644 --- a/README.md +++ b/README.md @@ -96,20 +96,27 @@ Write-Host -Foreground Green "`n[ZLocation] knows about $((Get-ZLocation).Keys.C ZLocation alters your prompt function to track the location. Meaning if you use this module with other modules that modify your prompt function (e.g. `posh-git`), then you'd need to adjust your [Powershell profile file](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7). The statement `Import-Module ZLocation` needs to be placed **after** the other module imports that modify your prompt function. -You can open `profile.ps1` using any of the below commands: +You can open `profile.ps1` using the below commands: ```powershell +# In case this is a fresh OS install the directory itself might not yet exist so create it. +New-Item -Type Directory (Split-Path -Parent $PROFILE.CurrentUserAllHosts) -ErrorAction SilentlyContinue +# Open the file. Use CurrentUserCurrentHost to get the profile for the current host, e.g. PowerShell ISE. notepad $PROFILE.CurrentUserAllHosts -notepad $env:USERPROFILE\Documents\WindowsPowerShell\profile.ps1 -notepad $Home\Documents\WindowsPowerShell\profile.ps1 ``` -Alternatively, type the below in your file explorer, and then edit the `profile.ps1` file with an editor of your choice: +Alternatively, type the below in your file explorer, and then create or edit the `profile.ps1` file with an editor of your choice: ``` %USERPROFILE%\Documents\WindowsPowerShell ``` +Or when using Powershell Core: + +``` +%USERPROFILE%\Documents\PowerShell +``` + License ------- From 6c80b10284b9028481b57743026c81425fcc2c49 Mon Sep 17 00:00:00 2001 From: stijn Date: Wed, 21 Apr 2021 09:30:00 +0200 Subject: [PATCH 3/3] Make prompt hook and addition of frequent folders configurable Make the module consume arguments and use this to configure 2 things: - prompt hook: currently prompt registration only works if no other module also overrides the prompt function after importing the ZLocation module. Normally fine, but it can be more convenient for users to just define their own prompt and call Update-ZLocation in it - adding frequent folders: this is nice, but it can also be particularly slow (> 200mSec on an above-average machine) and is not always used --- README.md | 9 ++++++++- ZLocation/ZLocation.psm1 | 30 ++++++++++++++++++++++++------ 2 files changed, 32 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index c1f9a65..3232f01 100644 --- a/README.md +++ b/README.md @@ -92,9 +92,16 @@ If you want to display some additional information about ZLocation on start-up, Write-Host -Foreground Green "`n[ZLocation] knows about $((Get-ZLocation).Keys.Count) locations.`n" ``` +Some features are configurable, these are the defaults: +```powershell +Import-Module ZLocation -ArgumentList @{AddFrequentFolders = $True; RegisterPromptHook = $True} +``` +- turn off `AddFrequentFolders` to not add directories from Explorer's QuickAccess to the ZLocation database automatically (this also results in faster loading times) +- turn off `RegisterPromptHook` to not automaticaly hook the prompt, see below + ### Note -ZLocation alters your prompt function to track the location. Meaning if you use this module with other modules that modify your prompt function (e.g. `posh-git`), then you'd need to adjust your [Powershell profile file](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7). The statement `Import-Module ZLocation` needs to be placed **after** the other module imports that modify your prompt function. +By default importing ZLocation alters your prompt function to track the location. Meaning if you use this module with other modules that modify your prompt function (e.g. `posh-git`), then you'd need to adjust your [Powershell profile file](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7). The statement `Import-Module ZLocation` needs to be placed **after** the other module imports that modifies your prompt function. As an alternative import the ZLocation module with `RegisterPromptHook=$False` and add a call to `Update-ZLocation $pwd` in your own prompt function. You can open `profile.ps1` using the below commands: diff --git a/ZLocation/ZLocation.psm1 b/ZLocation/ZLocation.psm1 index e99fc24..9619939 100644 --- a/ZLocation/ZLocation.psm1 +++ b/ZLocation/ZLocation.psm1 @@ -1,5 +1,18 @@ +param([parameter(Position=0, Mandatory=$false)] [Hashtable] $ModuleArguments=@{}) + Set-StrictMode -Version Latest +# Defaults from before we had arguments. +$defaultArgumentValues = @{ + AddFrequentFolders = $True; + RegisterPromptHook = $True; +} +foreach ($item in $defaultArgumentValues.GetEnumerator()) { + if (-not $ModuleArguments.ContainsKey($item.Name)) { + $ModuleArguments[$item.Name] = $item.Value + } +} + # Listing nested modules in .psd1 creates additional scopes and Pester cannot mock cmdlets in those scopes. # Instead we import them here which works. Import-Module "$PSScriptRoot\ZLocation.Service.psd1" @@ -63,9 +76,11 @@ function Register-PromptHook # On removal/unload of the module, restore original prompt or LocationChangedAction event handler. $ExecutionContext.SessionState.Module.OnRemove = { - Copy-Item function:\global:ZlocationOrigPrompt function:\global:prompt - Remove-Item function:\ZlocationOrigPrompt - Remove-Variable ZLocationPromptScriptBlock -Scope Global + if (Test-Path function:\global:ZlocationOrigPrompt) { + Copy-Item function:\global:ZlocationOrigPrompt function:\global:prompt + Remove-Item function:\ZlocationOrigPrompt + Remove-Variable ZLocationPromptScriptBlock -Scope Global + } } # @@ -252,9 +267,12 @@ function Get-FrequentFolders { } } -Get-FrequentFolders | ForEach-Object {Add-ZWeight -Path $_ -Weight 0} - -Register-PromptHook +if ($ModuleArguments.AddFrequentFolders) { + Get-FrequentFolders | ForEach-Object {Add-ZWeight -Path $_ -Weight 0} +} +if ($ModuleArguments.RegisterPromptHook) { + Register-PromptHook +} Set-Alias -Name z -Value Invoke-ZLocation