{"id":14064657,"url":"https://github.com/wtjones/PSDirTag","last_synced_at":"2025-07-29T18:33:42.673Z","repository":{"id":31139733,"uuid":"34699522","full_name":"wtjones/PSDirTag","owner":"wtjones","description":"DirTags are relative paths that appear as variables in the Powershell prompt that update as you navigate. Saves keystrokes when navigating folder structures.","archived":false,"fork":false,"pushed_at":"2017-12-10T13:44:59.000Z","size":36,"stargazers_count":23,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-11-23T10:34:54.458Z","etag":null,"topics":["navigation","powershell","workspace"],"latest_commit_sha":null,"homepage":"https://www.powershellgallery.com/packages/PSDirTag/","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wtjones.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-28T00:55:02.000Z","updated_at":"2024-11-15T22:52:52.000Z","dependencies_parsed_at":"2022-09-16T09:21:18.671Z","dependency_job_id":null,"html_url":"https://github.com/wtjones/PSDirTag","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wtjones%2FPSDirTag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wtjones%2FPSDirTag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wtjones%2FPSDirTag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wtjones%2FPSDirTag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wtjones","download_url":"https://codeload.github.com/wtjones/PSDirTag/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228040783,"owners_count":17860211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["navigation","powershell","workspace"],"created_at":"2024-08-13T07:03:59.800Z","updated_at":"2024-12-04T03:31:15.783Z","avatar_url":"https://github.com/wtjones.png","language":"PowerShell","funding_links":[],"categories":["PowerShell","Commandline Productivity"],"sub_categories":[],"readme":"PSDirTag\n=========\n\nOverview\n--------\n\nDirTags 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.\n\n\n### A basic example\n\nConsider this overly simple project structure:\n\n```\nproject1\n    - docs\n        - internal\n            - server\n    - src\n        - server\n```\n\nLet'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`...\n\n`PS C:\\project1\\src\\server\u003e subl ..\\..\\docs\\internal\\server\\new-feature.md`\n\nSimple enough, but we did have pay attention to current folder depth. Let's try a DirTag:\n\n_In dirtags.json:_\n\n```\n{\n  \"dirTags\": [\n    {\n      \"name\": \"docs\",\n      \"path\": \"docs\"\n    }\n  ]\n}\n\n```\n\nPSDirTag 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).\n\n```\nPS C:\\project1\\src\\server\u003e $docs\nC:\\project1\\docs\n```\n\nI use autocomplete:\n`PS C:\\project1\\src\\server\u003e subl $docs/i` and press {tab}...\n\nPowershell resolves the path...\n`PS C:\\project1\\src\\server\u003e subl C:\\project1\\docs\\internal\\`\n... and I may continue typing the command:\n`PS C:\\project1\\src\\server\u003e subl C:\\project1\\docs\\internal\\server\\new-feature.md`\n\n\n#### A slighter better example\n\nFolder name `docs` maybe bit a bit too generic, so let's narrow it down to internal server docs:\n\n_In dirtags.json:_\n\n```\n{\n  \"dirTags\": [\n    {\n      \"name\": \"serverdocs\",\n      \"path\": \"docs\\\\internal\\\\server\"\n    }\n  ]\n}\n```\n\nI can now tab-complete and use the new dirtag:\n```\nPS C:\\project1\\src\\server\u003e $serverdocs\nC:\\project1\\docs\\internal\\server\n```\n\nConsider 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:\n\n```\nPS C:\\features\\project2\\src\\server\u003e $serverdocs\nC:\\features\\project2\\docs\\internal\\server\n```\n\n\n#### The optional but complementary workspaceTags\n\n_WorkspaceTags_ provide:\n\n* A variable to an absoute path.\n* Derived variables for all dirtags that have a matching path under each workspace. Access another projects dirTags from anywhere.\n* Think _project folder_ or maybe a _vcs repository_.\n\n\n_Consider this dirtags.json:_\n\n```\n{\n  \"dirTags\": [\n    {\n      \"name\": \"serverdocs\",\n      \"path\": \"docs\\\\internal\\\\server\"\n    },\n    {\n      \"name\": \"servercode\",\n      \"path\": \"src\\\\server\"\n    }\n  ],\n  \"workspaceTags\": [\n    {\n        \"name\": \"mainline\",\n        \"path\": \"C:\\\\project1\"\n    },\n    {\n        \"name\": \"devline\",\n        \"path\": \"C:\\\\features\\\\project2\"\n    }\n  ]\n}\n```\n\nVariables `$mainline` `$devline` are now registered and work as expected.\n\n```\nPS C:\\\u003e cd $devline\nPS C:\\features\\project2\u003e\n```\n\nIn addition, each dirTag is checked for existence in each workspace. These variables now exist as well:\n\n`$mainline_serverdocs` points to `C:\\project1\\docs\\internal\\server`\n\n`$mainline_servercode` points to `C:\\project1\\src\\server`\n\n`$devline_serverdocs`  points to `C:\\features\\project2\\docs\\internal\\server`\n\n`$devline_servercode`  points to `C:\\features\\project2\\src\\server`\n\nAs with any variable, you may locate them via tab completion.\n\n\nUsage\n-----\n\n### Step 1: Installation\n\n#### Via [PowerShell Gallery](https://www.powershellgallery.com/packages/PSDirTag) (Powershell v5 required)\n\n    Install-Module -Name PSDirTag -Scope CurrentUser\n\n#### Via GitHub (PowerShell v3+ required)\n\nClone or download this repo to `$env:homepath\\documents\\WindowsPowerShell\\Modules`\n\n\n### Step 2: Configuration\n\nPlace a json config file named `dirtags.json` in your `$profile` folder. Add any dirTags or workspaceTags as desired.\n\n#### Example `dirtags.json` file:\n\n```\n{\n  \"dirTags\": [\n    {\n      \"name\": \"projtools\",\n      \"path\": \"src\\\\tools\"\n    },\n    {\n      \"name\": \"appimg\",\n      \"path\": \"resources\\\\data\\\\images\"\n    }\n  ]\n}\n```\n\n### Step 3: Load the module\n\n```\nImport-Module PSDirTag\n```\n\noptional verbose mode\n\n```\nimport-module PSDirTag -force -verbose -ArgumentList $true\n```\n\nEither of these lines may be placed in the PowerShell profile script, accessible via variable `$PROFILE`.\n\n\n### Cmdlets\n\nSee all tags in scope relative to the current directory.\n\n```\nGet-DirTags\n```\n\n\nUninstallation\n--------------\n\nRun the following\n\n```\nUnregister-DirtagsPrompt; Remove-Module PSDirTag\n```\n\nTODO\n----\n\n* Support multiple possible paths per tag.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwtjones%2FPSDirTag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwtjones%2FPSDirTag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwtjones%2FPSDirTag/lists"}