Powershell Profile

My Powershell $PROFILE module.

Documentation

WARNING: This script overwrites your Powershell $PROFILE. Make sure to take a backup of that before running any of the scripts in this repository, especially if you've done any customization previously.

You can backup your current profile with:

Copy-Item -Path "$($PROFILE)" -Destination "$($PROFILE).orig"

To restore it later, run:

Copy-Item -Path "$($PROFILE).orig" -Destination "$($Profile)"

Table of Contents

• Description
• Usage
• Custom Modules
  • Remove custom modules
• Developing
• Notes
• Links

Description

This repository includes a module named ProfileModule, which packages custom functions, variables, and aliases for use across PowerShell sessions—effectively turning $PROFILE into a module.

Each custom PowerShell profile sources a shared base template, which handles common setup tasks such as importing custom modules, configuring environment-specific options (e.g., PS5, PS7, PowerShell ISE), and loading the ProfileModule.

Custom profiles, like the Starship profile, build on top of this base. For example, the Starship profile automatically initializes Starship if it is installed.

The ProfileModule adds helpful aliases and functions to every session it's imported into. List the imported aliases with Show-ProfileModuleAliases and the functions with Show-ProfileModuleFunctions.

You can control which profile is installed by editing the config.json file. Each selected profile loads the shared base, then layers on its specific functionality.

Additionally, custom modules can be installed using the Install-CustomPSModules.ps1 script. These are modular and optional—just install what you need.

For example, on a work machine, you might want Azure helpers and Active Directory helpers, but skip the WeatherMod, which wraps wttr.in. To skip a module, simply answer n when prompted during installation.

Usage

• Clone the repository
• Copy config.example.json to config.json
  • Edit the file if you want to install a profile other than the default profile
  • You can also control which custom modules are installed by editing the custom_modules list in the config.json file
    • Add only the module name, for example if you want to install the DatetimeHelpers modules, just add "DatetimeHelpers" to the custom_modules list
• Install the profile
  • Automatic (scripted install)
    • Run Install-CustomProfile.ps1
    • This script will:
      • Import the PowershellProfileSetup module
      • Create a backup of your existing $PROFILE at $($PROFILE).bak.
        • You may still want to copy your old $PROFILE, like: cp $PROFILE "$($PROFILE).orig". This will prevent accidentally nuking any customizations you've made to your $PROFILE
      • Update the module's manifest file, ensuring all functions & aliases are exported properly.
      • Copy the shared base profile to your Powershell path
      • Copy the ProfileModule directory (the custom profile module) to your CustomModules/ directory in the same path as your $PROFILE.
      • Copy/update a custom profile (default: Default.ps1) to your machine's $PROFILE location.
        • Each custom profile imports the _Base.ps1 profile, which loads the ProfileModule and any custom modules defined in the config.json's custom_modules key.
        • To use a different profile, pass a -ProfileName <profilename>, where <profilename> is the name of a file in the Profiles/ directory without the .ps1 file extension.
          • i.e. -ProfileName Default would use ./Profiles/Default.ps1
  • Manual install
    • Open your Powershell profile path (get profile path with: split-path $PROFILE -parent)
      • For Powershell 5, it should be C:\Users\<your-username>\Documents\WindowsPowerShell
      • For Powershell 7 on Windows, it should be C:\Users\<you-username>\Documents\PowerShell
    • Copy the _Base.ps1 profile to your Powershell path
      • Also copy the profile (use the default profile if you are unsure).
    • (Optional) Install custom modules
      • Create a directory named CustomModules/ in your Powershell profile path
      • Copy any custom modules you want to use into this path.

After first setup, restart your terminal by closing & reopening it, or reload it in-place by running:

## Powershell 5
& "$PSHOME\powershell.exe" -NoExit -Command "Set-Location -Path '$PWD'"

## Powershell 7
& "$PSHOME\pwsh.exe" -NoExit -Command "Set-Location -Path '$PWD'"

To see a full list of the functions exported by this module, run: Get-Command -Module ProfileModule -Commandtype Function.

To see a full list of the aliases exported by this module, run: Get-Command -Module ProfileModule -CommandType Alias.

Custom Modules

This repository includes a number of custom modules in the Modules/Custom path. These modules can add additional functionality to your $PROFILE. The _Base.ps1 profile detects a folder CustomModules/ at the $PROFILE path on your host; if present, it will import any modules within, adding extra functionality to your $PROFILE. Keeping modules in this separate CustomModules/ directory prevents them from being auto-initialized by Powershell, allowing you to control module imports with the selected profile.

You can control which modules are installed automatically by the Install-CustomProfile.ps1 script by editing the custom_modules: [] key in your config.json. This key is a list of module names you want to install with your profile, corresponding to a directory in the custom modules path of this repository.

Remove custom modules

Run the [Remove-CustomModulesDir.ps1script](./scripts/Remove-CustomModulesDir.ps1) to uninstall all custom modules. This does not affect your custom profile, only the modules in the profile path'sCustomModules/` directory.

Developing

See the Developing docs

Notes

See the Notes documentation pages

Links

Check the docs for useful links