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 is a package of custom functions, variables, & aliases I set in my scripts, effectively turning my $PROFILE into a module.

Each custom Powershell profile loads the common base profile. The base template handles any common code I want available across all profiles, like importing custom modules, setting options based on which Powershell environment is running (PS5, PS7, Powershell ISE, etc), and importing the ProfileModule.

Each custom profile, i.e. the starship profile, source the _Base.ps1 file when they initialize to load that common/shared code.

The ProfileModule adds some helper methods and aliases to each Powershell session it is imported into.

By editing the config.json file, you can control which custom profile is installed. Each custom profile sources the _Base.ps1 profile, then builds on top of it. For example, the Starship profile automatically initializes Starship if it is installed.

In addition to each custom $PROFILE, there are custom modules you can install with the Install-CustomPSModules.ps1 script. Each module enhances the custom $PROFILE with extra functionality. These custom modules are modular, meaning you can add only the modules with functionality you want in your $PROFILE.

For example, on a work machine, you might want Azure helpers and Active Directory helpers, but not the silly WeatherMod, which wraps HTTP calls to wttr.in.

To skip installing certain modules, just answer n when prompted by the Install-CustomPSModules.ps1 script.

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 ful 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