https://github.com/mitchcapper/systempathgroups
https://github.com/mitchcapper/systempathgroups
Last synced: about 1 year ago
JSON representation
- Host: GitHub
- URL: https://github.com/mitchcapper/systempathgroups
- Owner: mitchcapper
- Created: 2025-02-11T21:44:06.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-02-12T01:41:06.000Z (over 1 year ago)
- Last Synced: 2025-04-05T08:35:24.188Z (about 1 year ago)
- Language: PowerShell
- Size: 14.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# SystemPathGroups
[](https://github.com/mitchcapper/SystemPathGroups/actions/workflows/build.yaml)
PowerShell module for managing grouped paths in Windows PATH environment variable. This was developed for the Github Actions Runner team to hopefully encourage them to implement better practices to avoid path pollution. At runner build time all the Paths are added to the system path var using `Add-ToPath` which then would allow for an easy github action that the user could use to either remove all default paths and add specific ones (best practice) or at least remove problematic ones from the path. This was mostly generated by GitHub Co-pilot / Aider.
## Table Of Contents
- [Simple Example](#simple-example)
- [Features](#features)
- [Configuration](#configuration)
- [Installation](#installation)
- [Cmdlet Reference](#cmdlet-reference)
- [Add-ToPath](#add-topath)
- [Syntax](#syntax)
- [Description](#description)
- [Parameters](#parameters)
- [Examples](#examples)
- [EXAMPLE 1](#example-1)
- [EXAMPLE 2](#example-2)
- [EXAMPLE 3](#example-3)
- [EXAMPLE 4](#example-4)
- [Add-PathGroupsToPath](#add-pathgroupstopath)
- [Syntax](#syntax-1)
- [Description](#description-1)
- [Parameters](#parameters-1)
- [Examples](#examples-1)
- [EXAMPLE 1](#example-1-1)
- [EXAMPLE 2](#example-2-1)
- [Remove-PathGroupsFromPath](#remove-pathgroupsfrompath)
- [Syntax](#syntax-2)
- [Description](#description-2)
- [Parameters](#parameters-2)
- [Examples](#examples-2)
- [EXAMPLE 1](#example-1-2)
- [EXAMPLE 2](#example-2-2)
- [EXAMPLE 3](#example-3-1)
## Simple Example
During initial platform image build add python and msys path options to the known path configuration, by default these are added to the system path too
```powershell
Add-ToPath -PathGroup Python -NewPath c:\python312
Add-ToPath -PathGroup Python -NewPath $env:LOCALAPPDATA\Programs\Python\Python312\Scripts
Add-ToPath -PathGroup MSYS64 -NewPath c:\msys64\ucrt64\bin
Add-ToPath -PathGroup MSYS64Nightly -NewPath c:\msys64-nightly\ucrt64\bin -AddToSystemPath $false
```
Then users could call:
```powershell
Remove-PathGroupsFromPath
Add-PathGroupsToPath Python MSYS64Nightly
```
Which would remove all known groups from the path by default and only add the ones the user cares about.
Otherwise if they just want to remove one problematic package in the default system path:
```powershell
Remove-PathGroupsFromPath MSYS64
```
## Features
- Group-based path management
- Persistent path configuration storage
- Support for paths with spaces and special characters
- Case-preserving path handling
- Forward/backward slash normalization
- Handles duplicate path prevention
## Configuration
- Paths are stored in: $env:ProgramData\SystemPathGroups\paths.json
## Installation
```powershell
Install-Module -Name SystemPathGroups
```
## Cmdlet Reference
### Add-ToPath
Adds a new path to both to the known paths configuration and optionally to the system path (true by default).
#### Syntax
```powershell
Add-ToPath
```
#### Description
This function adds a specified path to the paths configuration file with an associated path group.
If AddToSystemPath is true (default), also adds the path to the system path.
If AddToSystemPath is false, the path will only be saved to the configuration file.
#### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
|PathGroup|String|The group name to associate with the path in the configuration file.|
|NewPath|String|The file system path to add.|
|AddToSystemPath|Boolean|Optional. If true (default), adds the path to system path. If false, only stores in config.|
#### Examples
##### EXAMPLE 1
```powershell
Add-ToPath "DevTools" "C:\Tools\bin"
```
Adds C:\Tools\bin to the system path and associates it with the "DevTools" group.
##### EXAMPLE 2
```powershell
Add-ToPath -PathGroup "DevTools" -NewPath "C:\Tools\bin"
```
Same as above using named parameters.
##### EXAMPLE 3
```powershell
Add-ToPath "DevTools" "C:\Tools\bin" $false
```
Only adds C:\Tools\bin to the configuration file without modifying the system path.
##### EXAMPLE 4
```powershell
Add-ToPath -PathGroup "DevTools" -NewPath "C:\Tools\bin" -AddToSystemPath $false
```
Same as above using named parameters.
### Add-PathGroupsToPath
Adds paths associated with specified path groups to the system path.
#### Syntax
```powershell
Add-PathGroupsToPath
```
#### Description
This function adds paths to the system path environment variable based on their associated path groups
from the paths configuration file. If no path groups are specified, all paths from the configuration will be added.
#### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
|PathGroups|String[]|An optional array of path group names. If specified, only paths associated with these groups will be added.
If not specified, all paths from the configuration will be added.|
#### Examples
##### EXAMPLE 1
```powershell
Add-PathGroupsToPath -PathGroups "DevTools","TestTools"
```
Adds all paths associated with the "DevTools" and "TestTools" groups to the system path.
##### EXAMPLE 2
```powershell
Add-PathGroupsToPath
```
Adds all paths from the configuration file to the system path.
### Remove-PathGroupsFromPath
Removes paths associated with specified path groups from the system path.
#### Syntax
```powershell
Remove-PathGroupsFromPath
```
#### Description
This function removes paths from the system path environment variable based on their associated path groups.
If no path groups are specified, all paths from the configuration will be removed.
#### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
|PathGroups|String[]|An optional array of path group names. If specified, only paths associated with these groups will be removed.
If not specified, all paths from the configuration will be removed. Can be specified as multiple arguments.|
#### Examples
##### EXAMPLE 1
```powershell
Remove-PathGroupsFromPath "DevTools","TestTools"
```
Removes all paths associated with the "DevTools" and "TestTools" groups from the system path.
##### EXAMPLE 2
```powershell
Remove-PathGroupsFromPath "DevTools" "TestTools"
```
Same as above, but using multiple arguments instead of an array.
##### EXAMPLE 3
```powershell
Remove-PathGroupsFromPath
```
Removes all paths from the system path that are defined in the configuration file.