DirTags are relative paths that appear as variables in the Powershell prompt that update as you navigate. Saves keystrokes when navigating folder structures.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
functions
tests
CHANGELOG.md
LICENSE.md
PSDirTag.psd1
PSDirTag.psm1
readme.md
tests.ps1

readme.md

PSDirTag

Overview

DirTags are relative paths that appear as variables in the Powershell prompt that update as you navigate. It's geat for saving keystrokes when navigating folder structures.

A basic example

Consider this overly simple project structure:

project1
    - docs
        - internal
            - server
    - src
        - server

Let's say that we are working in project1/src/server. While editing server code, we may wish to create a documentation file in docs/internal/server...

PS C:\project1\src\server> subl ..\..\docs\internal\server\new-feature.md

Simple enough, but we did have pay attention to current folder depth. Let's try a DirTag:

In dirtags.json:

{
  "dirTags": [
    {
      "name": "docs",
      "path": "docs"
    }
  ]
}

PSDirTag will walk up the current path to find the first folder with that name, setting it as variable $docs. It wil update upon prompt refresh (more on that later).

PS C:\project1\src\server> $docs
C:\project1\docs

I use autocomplete: PS C:\project1\src\server> subl $docs/i and press {tab}...

Powershell resolves the path... PS C:\project1\src\server> subl C:\project1\docs\internal\ ... and I may continue typing the command: PS C:\project1\src\server> subl C:\project1\docs\internal\server\new-feature.md

A slighter better example

Folder name docs maybe bit a bit too generic, so let's narrow it down to internal server docs:

In dirtags.json:

{
  "dirTags": [
    {
      "name": "serverdocs",
      "path": "docs\\internal\\server"
    }
  ]
}

I can now tab-complete and use the new dirtag:

PS C:\project1\src\server> $serverdocs
C:\project1\docs\internal\server

Consider a scenario where it is common to work with multiple projects with the same folder structure. Assume there is another folder, project2, with a similar folder structure to the example above. I may access the same dirtag from anywhere in project2:

PS C:\features\project2\src\server> $serverdocs
C:\features\project2\docs\internal\server

The optional but complementary workspaceTags

WorkspaceTags provide:

  • A variable to an absoute path.
  • Derived variables for all dirtags that have a matching path under each workspace. Access another projects dirTags from anywhere.
  • Think project folder or maybe a vcs repository.

Consider this dirtags.json:

{
  "dirTags": [
    {
      "name": "serverdocs",
      "path": "docs\\internal\\server"
    },
    {
      "name": "servercode",
      "path": "src\\server"
    }
  ],
  "workspaceTags": [
    {
        "name": "mainline",
        "path": "C:\\project1"
    },
    {
        "name": "devline",
        "path": "C:\\features\\project2"
    }
  ]
}

Variables $mainline $devline are now registered and work as expected.

PS C:\> cd $devline
PS C:\features\project2>

In addition, each dirTag is checked for existence in each workspace. These variables now exist as well:

$mainline_serverdocs points to C:\project1\docs\internal\server

$mainline_servercode points to C:\project1\src\server

$devline_serverdocs points to C:\features\project2\docs\internal\server

$devline_servercode points to C:\features\project2\src\server

As with any variable, you may locate them via tab completion.

Usage

Step 1: Installation

Via PowerShell Gallery (Powershell v5 required)

Install-Module -Name PSDirTag -Scope CurrentUser

Via GitHub (PowerShell v3+ required)

Clone or download this repo to $env:homepath\documents\WindowsPowerShell\Modules

Step 2: Configuration

Place a json config file named dirtags.json in your $profile folder. Add any dirTags or workspaceTags as desired.

Example dirtags.json file:

{
  "dirTags": [
    {
      "name": "projtools",
      "path": "src\\tools"
    },
    {
      "name": "appimg",
      "path": "resources\\data\\images"
    }
  ]
}

Step 3: Load the module

Import-Module PSDirTag

optional verbose mode

import-module PSDirTag -force -verbose -ArgumentList $true

Either of these lines may be placed in the PowerShell profile script, accessible via variable $PROFILE.

Cmdlets

See all tags in scope relative to the current directory.

Get-DirTags

Uninstallation

Run the following

Unregister-DirtagsPrompt; Remove-Module PSDirTag

TODO

  • Support multiple possible paths per tag.