Using Subversion to Evangelize PowerShell

I've never been really comfortable with the Windows Command prompt - whenever I can, I grab Cygwin to give myself a more familiar (and powerful) command-line environment. I really appreciate the tools included with the Unix command shells, as well as the easy composability of the utilities that come with Unix.

Unsurprisingly, I was immediately attracted to PowerShell - a powerful replacement shell for Windows, with .NET integration, a Unix-like pipeline that works on objects rather than strings, and has plenty of built-in cmdlets. I installed it and tried to work. There were familiar commands (many of the Unix and Windows command names are aliased to their PowerShell equivalents), and these both helped and hindered - it was easy to find a command, but the options were slightly off, so the commands my fingers knew produced errors or unexpected results. Eventually I fell off the wagon, reverting to cmd.exe. Over the next year or so, I would return to PowerShell, only to stop using it again.

A few months ago, I was talking to the Guy in the Next Cubicle. He was also interested in PowerShell. We talked a little about the few scripts (neither of us had written new cmdlets) we'd made, and shared them. Having someone to talk to about PowerShell sparked something, and gave me the impetus to change my shortcuts to start PowerShell instead of cmd.exe. Unfortunately, sharing our scripts was awkward - usually via e-mail or instant messaging. In addition, as we improved our scripts, adding some to perform common tasks, we found the answers to some questions when people came for help was, "Well, if you had this PowerShell script, you'd just...", with no convenient way to get them the scripts.

Finally we decided to do something about it, and initiated a plan to help share our setup among our coworkers. We wanted a system that:

  • was easy to adopt,
  • made it easy to get and share scripts, and
  • was customizable - so people could have different prompts, for example

Inspired by Joey Hess's keeping your life in svn, we tried putting the whole profile directory under Subversion control. It was an easy choice, since everyone at the Day Job is already using Subversion to wrangle our source code.

Getting Started

Getting started with the profile is almost as easy as running

cd %USERPROFILE%\My Documents
svn checkout WindowsPowerShell

After this, the user will have a directory inside their My Documents directory that looks something like this:

profile directory skeleton

It's not quite usable, though. By default PowerShell doesn't allow scripts to be run, so the new profile will be of no benefit to users. To ease their pain, the profile directory contains a setup_powershell.bat which runs

powershell -Command "Set-ExecutionPolicy RemoteSigned"
After running setup_powershell.bat, all a user has to do is start PowerShell and they will benefit from the new profile.

Inside the WindowsPowerShell Directory

The first item of note inside the WindowsPowerShellDirectory is the Includes directory, which is populated with .ps1 files. Each .ps1 file contains functions to be loaded into memory and made available for the user's session. At startup, each of these .ps1 files are each dot-sourced (using the dot-source from a function trick I talked about last time).

Next, the Scripts directory, which is added to the user's $env:PATH. Each of the .ps1 files in the directory contains a standalone script that a user might choose to execute as they work. We have a number of Day Job-specific scripts as well as some Subversion helpers and two meta-scripts, designed to make it easier to work with the PowerShell profile.

Since new users won't be familiar with all the scripts in the profile, and because new scripts might be added at any time, we include a script to provide a quick synopsis of the available scripts: Get-ProfileHelp. It scans the Scripts directory, printing out, in an easy-to-read table, the Synopsis from the top of each script.



Get help for the PowerShellProfile scripts


Get-ScriptDirectory | Get-ChildItem -include ".ps1" -recurse | ForEach-Object { $name = $.Name; $name = $name.Remove($name.Length-4) $synopsis = "" $content = (Get-Content $.PSPath) for ($i = 0; $i -le ($content.length - 1); $i += 1) { if ( $content[$i] -like '.Synopsis*' ) { $synopsis = $content[$i+1].Substring(1).Trim() break } } $o = New-Object Object $o | Add-Member NoteProperty Name $name $o | Add-Member NoteProperty Synopsis $synopsis $o } | Format-Table -AutoSize

The Get-ScriptDirectory function just finds the location of the currently executing script. We'll see it later. Running the script gives output like this:

Name                     Synopsis
----                     --------
Copy-Branch              Copy an SVN branch, and optionally switch to the new branch
Get-ProfileHelp          Get help for the PowerShellProfile scripts
Get-SslCertificate       Load and display an SSL Certificate from a host
Import-ResharperSettings Import Resharper 4.5 settings from a file
Merge-Branch             Merge SVN commits back into the current working directory
Switch-Branch            Switch to a new SVN branch
Update-Profile           Get the latest version of the PowerShell profile from SVN

Rather than forcing users to navigate to the profile directory and run an svn command, the Update-Profile.ps1 script will automatically update the profile source:



Get the latest version of the PowerShell profile from SVN


svn update (Split-Path $profile)

User Profile Directories

In addition to the Includes and Scripts directories, each user of the PowerShell profile can have their own directory full of customizations. The name of the directory is taken from the $env:USERNAME variable. On startup, if the directory exists, any Include and Scripts directories are processed - being dot-sourced or added to the path, respectively. This allows users to have their own personal scripts and functions. In addition, the profile.ps1 from the directory is dot-sourced.

If a user runs PowerShell and doesn't already have a profile directory, a welcome message is printed to the screen, explaining basic usage of the profile. Then a profile directory is created and populated with an empty profile.ps1 to get the user started and to keep them from being welcomed again.

Some users choose to commit their personal profile directories to the repository, and some don't - there's no requirement either way. If someone chose, they could even use an svn:externals on the WindowsPowerShell directory and host their personal directory in another part of the repository or even a different repository.

Putting it All Together

Finally we see the Microsoft.PowerShell_profile.ps1 file that orchestrates all this:

# Will turn on extra output to help debug profile-loading.

Don't check in as "true"

$verbose = $false

A convenience function to get the directory the current script lives in

- useful for importing from relative paths

function Get-ScriptDirectory { $Invocation = (Get-Variable MyInvocation -Scope 1).Value Split-Path $Invocation.MyCommand.Path }

function Include-ProfileDirectory([string] $directory) { # Load every file in the Includes subdirectory - # hopefully they can be loaded in any order. # The Includes directory should contain files that define functions and # filters to be executed later, but not scripts that need to do # something when the file is sourced. if ( Test-Path ($directory + '\Includes') ) { Get-ChildItem -Path:($directory + '\Includes') -Filter:*.ps1 | ForEach-Object { if ( $verbose ) { Write-Output ("importing " + $.PSPath) } . $.PSPath } }

# The Scripts directory should contain PowerShell scripts that someone
# might want to be executed, so we'll add it to our path.
if ( Test-Path "$directory\Scripts" )
    $env:PATH = "$($env:PATH);$directory\Scripts"


dot-source the Include-ProfileDirectory function. If we run it

directly, all the included functions will be scoped inside the

Include-ProfileDirectory command, and inaccessible to the user.

. Include-ProfileDirectory(Get-ScriptDirectory)

Look for user-specfic customizations. If they're there, load them.

$userProfileDir = ((Get-ScriptDirectory) + '\' + $env:USERNAME) if ( Test-Path $userProfileDir ) { if ( $verbose ) { Write-Output "including $userProfileDir" } . Include-ProfileDirectory($userProfileDir)

$userProfile = ($userProfileDir + '\profile.ps1')
if ( Test-Path $userProfile )
    . $userProfile

} else { Write-Host -foregroundColor yellow -backgroundColor darkblue @"

Welcome to the DayJob PowerShell Profile. It looks like this is your first time here, so I'll create a new profile for you. This profile will be called


If you want to customize your PowerShell experience, you can edit this file. Eventually you may want to modify files in the containing directories, but keep in mind that those changes will affect other users.

Have fun!


New-Item -path  $userProfile -itemType "file" -Force > Out-Null