nickcox / cd-extras

cd-extras =========== • cd-extras • Navigation commands • Parameters • Frecency • Database • Bookmarks • Output • Completions • Listing available navigation targets • cd enhancements • Path shortening • Multi-dot cd • No argument cd • Two argument cd • Enhanced completion for cd and others • Single and double periods • Multi-dot completions • Variable based completions • Extending completion to other commands • Colourised completions • AUTO CD • Tilde • Multi-dot • CD PATH • CDABLE VARS • Related commands • Get-Up gup • Get-Stack dirs • Clear-Stack dirsc • Expand-Path xpa • Compatibility • OS X & Linux • Alternative providers • Install • Configure • cd-extras options • Navigation helper key handlers • Using a different alias Navigation commands *Quickly navigate backwards, forwards, upwards or into recently used directories* [ Watch ] _cd-extras_ provides the following navigation commands and corresponding aliases (shown in parens): • , ( or ) • , ( or ) • , ( or ) • , ( ) • , ( ) :point_right: That's and , without a space. and , with a space, also work but you won't get auto-completion. :point_right: Repeated uses of keep moving backwards towards the beginning of the stack rather than toggling between the two most recent directories as in vanilla bash, neither will it echo the path of the target directory. Use ( ) to toggle between directories and the switch if you need to output the new directory path. Parameters , , , and each take an optional argument, which navigates by the given number of steps. , and also accept a string, , used to select the nearest matching directory from the available locations. Given a , _cd-extras_ will match the first directory whose leaf name contains the given string⁽¹⁾. If none is found then it will attempt to match against the full path of each candidate directory⁽²⁾. and use a slightly different name matching logic which is cribbed from [Zoxide][3]. Each command takes one or more where each term must match part of a target directory, in order, and the _last_ (or only) term must match the target's leaf name. Frecency While ( ) and ( ) work with the recent directories list in the order that they were most recently visited, ( ) and ( ) use a frecency algorithm as described in the [Zoxide docs][4]. Database Recent locations, frecent locations, and bookmarks share a datastore which is not persisted between sessions by default. You can opt in to persisting to a CSV file by setting the option. The size of the datastore - whether persisted or not - is configured with the option. Once the limit is reached, the least recently entered directories are discarded after every directory change although bookmarked directories are never dropped. You can manually remove entries with the command or by using the switch with and . This command expects a parameter, , which is a PowerShell wildcard pattern used to match against the directory path or a complete directory leaf name. If no pattern is given then the current working directory is removed. Bookmarks Directories may be bookmarked with the command ( ), boosting those directories to the top of the frecency list. takes a parameter which can be omitted when bookmarking the current directory. ( ) and ( ) provide a or switch with the same functionality. Output Each navigation command includes a switch to return a value in case you need a reference to the resulting directory. The value will be if the action wasn't completed - for example, if there was nothing in the stack or you attempted to navigate up from the root. Completions Auto-completions are provided for each of , , , and . Assuming the [_PSReadLine_][0] function is bound to tab... ...then tabbing ( ) through any of the navigation helpers will display a menu based completion. The _ _ option controls how completion text is displayed. When _IndexedCompletion_ is on and more than one completion is available, the completions offered are the *indices* of each corresponding directory; the directory name is displayed in the menu below. The full directory path is given in the tooltip if you have _PSReadLine_ tooltips enabled. _cd-extras_ detects _PSReadLine_ options in order to set _IndexedCompletion_ at startup. If the _PSReadLine_ option is bound to at least one key combination then _IndexedCompletion_ is turned on by default. You can turn it off if you prefer. It's also possible to tab-complete , , , and using a partial directory name (i.e. the parameter). Listing available navigation targets As an alternative to menu completion you retrieve a list of available targets with: • ( ) • ( ) • ( ) • ( ) • ( ) enhancements **Shortcuts and tab completions for the command** [ Watch ] provides a proxy to - called - and aliases it to by default, giving it several new abilities: • Path shortening • Multi-dot • No argument • Two argument • Enhanced tab completions Path shortening If an unambiguous match is available then can change directory using an abbreviated path. This effectively changes a path given as, into or into . If you're not sure whether an unambiguous match is available then just hit tab to pick from a list of potential matches instead. Word delimiters ( , , by default) are expanded around so a segment containing is expanded into . :point_right: Powershell interprets a hyphen at the start of an argument as a parameter name. So while you can do this... ... you need to escape this: Pairs of periods are expanded between so, for example, a segment containing is expanded into . Directories in will be also be shortened. uses the same expansion algorithm when enabled. Multi-dot In the same way that you can navigate up one level with , supports navigating multiple levels by adding additional dots. works the same way if enabled. No argument If the _ _ option is defined then without arguments navigates into that directory ( by default). This overrides the out of the box behaviour of PowerShell >=6.0, where no-arg _always_ nav…