PoShWarp is a PowerShell port of the wd
plugin for zsh. It aims to offer the same convenience that
wd offers in zsh
alongside some idiomatic PowerShell commands.
If you have PsGet installed, you can simply execute:
Otherwise, for a manual installation:
- Create a
PoShWarpdirectory in your modules folder. You can determine where this is by looking at the
PoShWarp.psm1and place it in the newly created
- PoShWarp should automatically load next time you start PowerShell. If this
does not happen, add
Import-Module PoShWarpto your
Our systems contain projects strewn all over our systems. We aim to keep things organised but something will always disrupt our careful organisation, and it becomes far to easy to forget where all these things end up living. With PoShWarp, this problem becomes far more manageable because these commonly-used locations can be given names.
Let's say we have a folder that contains a set of projects:
E:\Projects> Get-ChildItem Directory: Microsoft.PowerShell.Core\FileSystem::E:\Projects Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 24/11/2014 17:11 <DIR> CunningEmbeddedProject d---- 24/11/2014 17:11 <DIR> SuperAwesomeProject d---- 24/11/2014 17:11 <DIR> TrendyWebProject
We can can create warp-names for two of these projects like so:
E:\Projects> cd .\SuperAwesomeProject\ E:\Projects\SuperAwesomeProject E:\Projects\SuperAwesomeProject> New-WarpLocation awesome Name Path ---- ---- awesome E:\Projects\SuperAwesomeProject E:\Projects\SuperAwesomeProject> New-WarpLocation trendy ..\TrendyWebProject Name Path ---- ---- trendy E:\Projects\TrendyWebProject
These two bindings now appear in a system-wide warp-map that exists in the
same directory as your
$profile by default. You can relocate the warp-map by
POSHWARP_MAPFILE environment variable to point where you would
prefer it to be. Now our sample warp-map looks like:
E:\> Get-WarpLocation Name Path ---- ---- awesome E:\Projects\SuperAwesomeProject trendy E:\Projects\TrendyWebProject
Now we can enter into either project directory without needing to remember the path:
C:\> Select-WarpLocation awesome E:\Projects\SuperAwesomeProject> Select-WarpLocation trendy E:\Projects\TrendyWebProject>
Granted, this example is rather simple but visiting directories frequently can
get annoying quite swiftly. Especially if those paths are particularly deep or
if they contain confusing or similar sub-directories. With PoShWarp,
to that arcane directory can now be replaced with
or the far simpler
Select-WarpLocation [-WarpName] <String> [-PassThru] [<CommonParameters>]
Searches the warp-map for the specified entry and sets the location accordingly.
Select-WarpLocation will search the active warp-map file for the entry with the
given name and attempt to
Set-Location to the corresponding path. An error
will be raised if no entry with the given name is found, of if the named entry
exists but points to a non-existent directory.
|WarpName||String||Entry name to search for in the warp-map.|
|PassThru||Switch||Return the new directory object after changing into it.|
New-WarpLocation [-WarpName] <String> [[-Path] <String>] [<CommonParameters>]
Creates a new entry in the current warp-map.
A new entry will be added to the warp-map currently active using either the current or specific directory path. If the does not exist, no entry will be created. A warp-map XML file with be created if one does not already exist.
|WarpName||String||Name for the new warp-map entry.|
|Path||String||Path to assign to WarpName. Defaults to the current directory.|
Remove-WarpLocation [[-WarpName] <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
Removes the specified entry from the active warp-map.
Searches the active warp-map for the named entry and then removes it. The current directory will be used as a search term if no name is given. All entries that meet the criterion will be removed. An empty warp-map file will not be created if one does not already exist.
|WarpName||String||Warp-map entry name to search for.|
Get-WarpLocation [[-WarpName] <String>] [[-Path] <String>] [<CommonParameters>]
Gets the entries from the warp-map, optionally filtering by name or path.
Get-WarpLocation will return all the entries from the warp-map that meet the given search criteria. Zero or more entries will be returned. Both a warp-name and a path may be specified, and both must match to return any results. No error will be raised if the query results in no matches.
|WarpName||String||Name to search for in the warp-map.|
|Path||String||Path to search for in the warp-map.|
Repair-WarpMap [-WhatIf] [-Confirm] [<CommonParameters>]
Removes all invalid directory references from the warp-map.
Over time, a living warp-map can retain entries pointing to directories that no longer exist. Repair-WarpMap checks every entry in the warp-map and removes any that reference a directory that has been deleted. Multiple entries pointing to the same directory will remain unchanged provided that they point to a directory that still exists.
wd [-WarpName <String>] [-Path <String>] [-PassThru] [[-argv] <Object>] [-WhatIf] [-Confirm] [<CommonParameters>]
Provides all warp-map functionality under a single utility command.
wd is a clone of the command offered in the eponymous zsh package. It
provides an interface to all of the other commands in PoShWarp:
wd add, wd new -> New-WarpLocation wd rm, wd del -> Remove-WarpLocation wd ls, wd list -> Get-WarpLocation wd clean, wd repair -> Repair-WarpMap wd help -> Get-Help wd
wd also supports
wd show <WarpName> which lists all entries that share the
given name. This has been provided as a convenience as it simply maps onto
Get-WarpLocation, and also for compatibility with the original
wd treats the first argument as a warp-map entry name if it does not match one
of the sub-commands. In this instance
wd <WarpName> maps onto
Select-WarpLocation -WarpName <WarpName>.
wd exists for compatibility with the zsh package, it primarily relies on
positional arguments as follows:
wd <sub-command> <WarpName> <Path>. However,
named parameters are also supported to make good use of PowerShell.
|WarpName||String||Name for the warp-map entry.|
|Path||String||Path for the warp-map entry.|
|PassThru||Switch||Only used when selecting a warp location: flag propagates directory to
All warp-locations created by
New-WarpLocation are saved
in an XML file called the warp-map. By default, this file is named
WarpMap.xml and will be created in the same directory as your
it can be placed elsewhere using the
POSHWARP_MAPFILE environment variable.
The commands in the example given above would lead to the following warp-map:
<?xml version="1.0"?> <WarpMap> <Location Name="awesome" Path="E:\Projects\SuperAwesomeProject" /> <Location Name="trendy" Path="E:\Projects\TrendyWebProject" /> </WarpMap>
The format is largely self-explanatory and has been kept deliberately simple. Warp-maps maybe be edited by hand and may include custom XML if you wish to use the file for multiple purposes. There is no guarantee that the additional elements will be left undamaged, but PoShWarp commands have been designed to modify only the elements that are necessary. Of course, there is a risk that a future version of PoShWarp may include additional XML that may conflict with any custom elements that have been added.
Every exported PoShWarp command includes a corresponding set of tests that can
be executed using Pester. Running the
Invoke-Pester command from the source directory will load
and create an environment for the tests to operate in. This environment
includes a warp-map and a suitable directory structure which will be removed as
part of the tear-down.
The MIT License (MIT)
Copyright (c) 2014-2015 Kier Dugan
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.