winprefs

macOS users: please see macprefs for an equivalent tool.

This package dumps a registry path to equivalent reg commands. It contains two commands. Save-Preferences creates a batch script composed of reg commands for copying into a script. Write-RegCommands is effectively the same but requires a path argument and only writes to standard output.

By default both commands default to a maximum depth of 20. Save-Preferences defaults to path HKCU:.

Note that by default only HKCU: and HKLM: are mounted in PowerShell. Others need to be mounted and must be under the appropriate name such as HKU for HKEY_USERS.

Keys/values are skipped under these conditions:

• Depth limit (default: 20); this can be changed by passing -MaxDepth LIMIT or -m LIMIT.
• Key that cannot be read for any reason such as permissions.
• Value contains newlines.
• Value has type REG_UNKNOWN.
• Value is filtered. Pass -S or --no-settings to disable filters.

An example of an always skipped key under normal circumstances is HKLM\SECURITY, even if this is run as administrator.

Be sure to set up Git with your user name and email (git config --global user.email, etc) before using the commit feature.

Values can be filtered by adding wildcard strings to HKCU\Software\Tatsh\WinPrefs\Filters (HKLM will be used for users in the administrator group). Example to ignore all values that have Cache in the path:

reg add "HKLM\Software\Tatsh\WinPrefs\Filters" /v ThisCanBeAnything /t REG_SZ /d "*\Cache\*" /f

On first launch, a default set of filters will be added. If you do not want these, delete the values under the key but do not delete the key HKLM\Software\Tatsh\WinPrefs\Filters.

WARNING: If you save an entire tree such as HKLM: to a file and attempt to run said script, you probably will break your OS. The output of this tool is meant for getting a single command at a time, testing it, and then using it in an appropriate script. The author will not be held responsible for any damages.

Installation

Install-Module -Name WinPrefs

Usage

Save-Preferences
# or the alias:
prefs-export

Save-Preferences generates an exec-reg.bat (default name) file and saves to ${env:APPDATA}\prefs-export by default. This can be changed by passing -OutputDirectory DIR (or -o DIR). The file name can be changed by passing -OutputFile FILE (or -f FILE).

The format can be changed with the -Format argument. Accepted format strings:

• It accepts switch -Commit/-c to initialise and commit to a Git repository in the output directory. It also accepts a -DeployKey PATH parameter and will push if this is specified. Any other Git management such as the branch name, etc must be managed in the output directory manually.

Write-RegCommands HKCU:
# or the alias
path2reg HKCU:

Write-RegCommands prints out equivalent reg commands to reproduce the keys/values at the given path. reg command output is escaped for Batch file only. No variables will be present in the output. If you want to use a reg command in PowerShell you need to replace %% with %.

Automated Usage

You can create a scheduled task that will run every 12 hours to backup a registry path. Register-SavePreferencesScheduledTask (winprefs-install-job) can be called multiple times with different -Path arguments. Like Save-Preferences it can automatically commit to a repository and push.

Calling Register-SavePreferencesScheduledTask multiple times with the same -Path argument will not break anything. If a task with the same name already exists, it must be unregistered before its replacement can be made.

Any task can be uninstalled with Unregister-SavePreferencesScheduledTask (winprefs-uninstall-job) with the same -Path argument.

Uninstallation

Delete APPDATA%\prefs-export. Also be sure to delete tasks under tat.sh\WinPrefs in Task Scheduler (taskschd.msc).

Examples

Save <tt>HKEY_LOCAL_MACHINE\Control Panel</tt> with a depth of 1

prefs-export -o . -m 1 -Path 'HKCU:\Control Panel\Desktop'
cat exec-reg.bat

Output:

reg add "HKCU\Control Panel\Desktop\Colors" /v "ActiveBorder" /t REG_SZ /d "212 208 200" /f
reg add "HKCU\Control Panel\Desktop\Colors" /v "ActiveTitle" /t REG_SZ /d "10 36 106" /f
REM ...

Export, commit with Git and push with a key

Dump WindowMetrics as C code

Write-RegCommands HKCU:\Environment -Format c

Output:

data = { 0xee, 0xff, 0xff, 0xff, /* ... */}; RegSetKeyValue(HKEY_CURRENT_USER, TEXT("Control Panel\\Desktop\\WindowMetrics"), TEXT("CaptionFont"), REG_BINARY, (LPCVOID)&data, 92);

Dump a single value

Write-RegCommands HKCU:\Environment\OneDrive

Output:

reg add "HKCU\Environment\OneDrive" /v "OneDrive" /t REG_EXPAND_SZ /d "%%USERPROFILE%%\OneDrive" /f

Dump a binary value

Write-RegCommands 'HKCU:\Control Panel\Desktop\WindowMetrics\StatusFont'

Output:

reg add "HKCU\Control Panel\Desktop\WindowMetrics\StatusFont" /v "StatusFont" /t REG_BINARY /d 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f505152535455565758595a5b /f

Native version

The PowerShell module makes use of the native code with DllImport to get a significant speed increase in making registry queries and performing I/O. A native binary winprefs.exe can also be built that can be used without needing PowerShell installed and it should work with XP and newer. If built as a a 32-bit binary, the native binary should be compatible with Windows 2000 and newer. It even works with Wine.

The path name should be of the form: HIVE\Key\SubKey. Do not leave a trailing \.

Usage is similar to the PowerShell version:

Usage: winprefs.exe [OPTION...] [REG_PATH]
 
If a path to a value name is specified, the output directory argument is ignored and the line is
printed to standard output.
 
Options:
  -F, --format=FORMAT Format to output. Options: c, cs, c#, ps, ps1, powershell, reg. Default: reg.
  -K, --deploy-key    Deploy key for committing.
  -c, --commit        Commit changes.
  -d, --debug         Enable debug logging.
  -f, --output-file   Output filename.
  -m, --max-depth=INT Set maximum depth.
  -o, --output-dir    Output directory.
  -h, --help          Display this help and exit.

Note the equivalent format names (case-insensitive):

• C#: cs, c#
• PowerShell: ps, ps1, powershell

Development

Requirements:

• Windows
• Yarn

Building

Visual Studio

On Windows with Visual Studio installed:

mkdir build
cd build
cmake -Wno-dev ..
cmake -G 'Visual Studio 17 2022' --build . -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

Using the VS developer environment shell is not required but it may help.

After building winprefs.exe will be in build\native\Release\winprefs.exe.

MinGW

Note: The PowerShell module (C# code) is only buildable with Visual Studio 2022.

mkdir build
cd build
cmake -G Ninja -Wno-dev ..
cmake --build . --config Release --verbose

After building winprefs.exe will be in build/native/winprefs.exe.

Cross-compiling

mkdir build
cd build
cmake -G Ninja -DCMAKE_BUILD_WITH_INSTALL_RPATH=ON -DCMAKE_C_COMPILER=/usr/lib/mingw64-toolchain/bin/x86_64-w64-mingw32-gcc -DCMAKE_SYSTEM_NAME=Windows -Wno-dev ..
cmake --build . --config Release --verbose

You may need to adjust paths above.

After building winprefs.exe will be in build/native/winprefs.exe.

Tasks

• yarn format: to format the project's files.
• yarn qa: Perform a QA check.