PSDotFiles

A simple dotfiles management framework for Windows built on PowerShell.

Purpose

PSDotFiles aims to provide a simple yet powerful and flexible framework for managing your dotfiles on Windows systems. The design is heavily influenced by GNU Stow, which works by symlinking the contents of one or more folders into another folder. In this way, a collection of dotfiles can be easily divided into per-application folders (e.g. git, sublime, vim, etc...).

PSDotFiles implements this basic design but with a PowerShell-centric approach using a simple set of cmdlets.

Requirements

PowerShell 5.0

The only software requirement is PowerShell 5.0, however, it's not yet in widespread distribution.

The below table should help make things simple:

Operating System	Installation Steps
Windows Vista	Not available
Windows 7	Download WMF 5.0
Windows 8	Not available
Windows 8.1	Download WMF 5.0
Windows 10 (RTM/LTSB)	Not available
Windows 10 (1511/TH2)	Built-in
Windows 10 (1604/RS1)	Built-in
Windows Server 2008	Not available
Windows Server 2008 R2	Download WMF 5.0
Windows Server 2012	Download WMF 5.0
Windows Server 2012 R2	Download WMF 5.0

If PowerShell 5.0 is not available for your operating system then I'm afraid you're out of luck for now. You may wish to indicate your interest in a backport in this issue.

Folder Structure

PSDotFiles expects a dotfiles folder to be structured as multiple folders each containing the files and folders comprising a particular application's configuration. These top-level folders are referred to by PSDotFiles as components. The files and folders in each component's folder should be relative to a well-known top-level folder (e.g. your profile folder, which is the default target in PSDotFiles). The actual list of well-known folders are those in the [Environment.SpecialFolder](https://msdn.microsoft.com/en-us/library/system.environment.specialfolder.aspx) enumeration.

A simple dotfiles folder structure might look like this:

dotfiles
| --- clink
   | --- clink_inputrc
   | --- settings
| --- conemu
   | --- ConEmu.xml
| --- git
   | --- .gitattributes
   | --- .gitconfig 
   | --- .gitignore
| --- posh
   | --- Modules
      | --- MyModule
         | --- MyModule.psm1
   | --- profile.ps1
| --- vim
   | --- .vimrc

Installing

PowerShellGet

The latest release of the module is published to the PowerShell Gallery for installation via the PowerShellGet module:

Install-Module -Name PSDotFiles

You can find the module listing here.

ZIP File

Download the ZIP file of the latest release and unpack it to one of the following locations:

• Current user: C:\Users\<your.account>\Documents\WindowsPowerShell\Modules\PSDotFiles
• All users: C:\Program Files\WindowsPowerShell\Modules\PSDotFiles

Git Clone

You can also clone the repository into one of the above locations if you'd like the ability to easily update it via Git.

Did it work?

You can check that PowerShell is able to locate the module by running the following at a PowerShell prompt:

Get-Module PSDotFiles -ListAvailable

Configuring

Before you can use PSDotFiles you should set the $DotFilesPath variable to the location of your dotfiles folder. For example:

$DotFilesPath = "C:\Users\<your.account>\dotfiles"

So that you don't have to enter this into every new PowerShell session it's a good idea to add this to your PowerShell profile:

• All PowerShell hosts (including the ISE): $HOME\Documents\WindowsPowerShell\profile.ps1
• Only the Microsoft.PowerShell shell: $HOME\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

If you're unsure which to use, just choose the first.

Quickstart

The module only exports three commands through which all dotfiles management occurs:

# Enumerates available dotfiles components
Get-DotFiles

# Installs one or more dotfiles components
Install-DotFiles

# Removes one or more dotfiles components
Remove-DotFiles

All commands have built-in help and examples which can be accessed with Get-Help <command>.

Only Install-DotFiles and Remove-DotFiles will modify your system by creating or removing the appropriate symlinks.

Both Install-DotFiles and Remove-DotFiles support PowerShell's standard -WhatIf and -Confirm parameters.

Troubleshooting

Encountering unexpected behaviour or other problems? You may wish to run the problematic command with the -Verbose parameter for more details. You can also add the -Debug parameter for even more details on the command processing.

If you think you've found a bug please consider opening an issue so that I can look into it and hopefully get it fixed!

License

All content is licensed under the terms of The MIT License.