🪟 dotfiles-Windows

The native Windows host — PowerShell, Windows Terminal, scoop/winget, and the WSL2 bridge.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Languages
   • Tools
2. Getting Started
3. Layout
4. Contributing
5. License
6. Contact

About The Project

dotfiles-Windows is the native-host layer — one node in a cross-platform dotfiles system. It owns the Windows host: PowerShell 7 as the daily-driver shell, Windows Terminal, the scoop/winget package layer, psmux (native tmux), and the bridge into Linux distros running under WSL2.

Unlike every OS repo, Windows does not vendor Core as a git subtree. The shared config is replicated natively in PowerShell — the powershell/core/ fragments mirror the feel of the zsh loader — so only three cross-shell assets are synced from dotfiles-core: nvim/ (via nvim-sync.ps1), starship/starship.toml (via starship-sync.ps1) and theme/palette.toml (via theme-sync.ps1, then rendered into the terminal layer by gen-theme.ps1). It also deliberately does not configure WSL distros — Core, dotfiles-Debian and dotfiles-Offense configure themselves from their own repos inside WSL. This repo makes the host excellent, then gets out of the way. Full docs live on the documentation site.

The system is three layers; Windows is a host that replicates Core rather than vendoring it:

Layer	Lives in	Owns
Core	dotfiles-core → vendored into every OS repo's core/ (Windows replicates it in pwsh instead)	zsh, tmux, nvim, git, starship — identical everywhere
OS-native	dotfiles-{MacBook,Windows,Fedora,Arch,Debian,openSUSE,Alpine,Gentoo} (Windows is the native host)	package manager, clipboard, paths
Role	dotfiles-Offense, dotfiles-Defense	offensive / defensive tooling (Windows bridges to Kali under WSL)

Languages

• 

Tools

• 
• 
• 
• 

(back to top)

Getting Started

Step 0 — provision a fresh box

Stock Windows ships neither git nor PowerShell 7, so the one-liner below cannot run on a brand-new machine until you lay the foundation. Do that first:

winget install Git.Git Microsoft.PowerShell
git clone https://github.com/dotgibson/dotfiles-Windows.git ~/dotfiles-Windows
cd ~/dotfiles-Windows
winget configure -f configuration.dsc.yaml --accept-configuration-agreements

configuration.dsc.yaml is idempotent and reconciling: it installs Windows Terminal, PowerShell 7, WSL and Git, and enables Developer Mode — which is what lets install.ps1 create real symlinks instead of degrading to copies.

Enable Developer Mode rather than running elevated. Scoop's installer refuses to run from an administrator shell, so elevating to win symlinks costs you the entire package phase.

Then reopen PowerShell 7 (pwsh) and continue below.

Prerequisites

PowerShell 7 (pwsh), git, and Developer Mode — all provided by Step 0. Already have them? Skip straight to the install.

Installation

irm https://raw.githubusercontent.com/dotgibson/dotfiles-Windows/main/bootstrap.ps1 | iex

The one-liner is integrity-gated — verify the script against its pinned SHA-256 before piping to iex (the docs show the hash-checked form). Or, from the clone you already made in Step 0, run the installer directly:

cd ~/dotfiles-Windows
.\install.ps1                # packages + symlinks (idempotent)
.\install.ps1 -SkipPackages  # just re-wire links
.\install.ps1 -DryRun        # preview; -Help for the full option list

Then open a new PowerShell window, set your name/email in ~/.gitconfig.local, and review ~/.wslconfig + wsl --shutdown to apply mirrored networking.

(back to top)

Layout

dotfiles-Windows/
├── install.ps1                  bootstrap (env var, packages, symlinks)
├── uninstall.ps1                remove repo symlinks (optionally restore backups)
├── .githooks/pre-commit         runs tests/Invoke-Validation.ps1 before commits
├── powershell/
│   ├── profile.ps1              loader (core→os→local)
│   ├── core/                    aliases, shared lib, tool inits, functions, completions, help
│   │     00-aliases  05-lib  08-git-safety  10-tools  15-update  20-functions  25-television
│   │     40-op  45-crypto  50-completions  55-help  57-health-nudge
│   ├── os/                      windows helpers + wsl bridge + psmux + remote + maint + doctor
│   │     30-windows  31-wsl-bridge  32-psmux  33-psmux-pill  34-remote  40-maint  45-doctor  48-core
│   └── local.ps1.example        copy to local.ps1 (gitignored)
├── maint/Maintenance.ps1        unattended daily maint runner (Task Scheduler)
├── windows-terminal/settings.json
├── starship/starship.toml       same prompt as the fleet (tokyonight-storm)
├── git/ (.gitconfig, .gitignore_global)
├── ssh/config                   hardened (no ControlMaster on Win OpenSSH)
├── psmux/psmux.conf             native host tmux (psmux), symlinked to ~/.config/psmux/
│       psmux.reset.conf  scripts/   (keybinds split out + popup helper scripts)
├── desktop/                     opt-in tiling desktop (GlazeWM + Zebar), symlinked to ~/.glzr
├── nvim/                        symlinked to %LOCALAPPDATA%\nvim (mirrors Core)
├── wsl/windows.wslconfig.example  canonical host WSL2 config (mirrored net)
├── packages/ (scoopfile.json, winget.json, Install-Packages.ps1)
├── docs/ (TOOLS.md, PORTING-NOTES.md, ARCHITECTURE-AUDIT.md, PACKAGE-OWNERSHIP.md, REMOTE-ACCESS.md)
└── CONTRIBUTING.md  SECURITY.md  .github/ (workflows, CODEOWNERS, templates)

powershell/core/ is native pwsh config (not a vendored subtree); nvim/, starship/ and theme/ are the three assets mirrored from dotfiles-core. The deep detail — the fragment loader and coverage gate, the supply-chain-gated bootstrap, and the WSL bridge — is written up on the hub, alongside the Windows architecture audit:

→ dotfiles-Windows on the documentation hub

(back to top)

Contributing

This repo owns the Windows host directly, so its contribution rules differ from the vendored-Core OS repos:

1. Host config lives here — edit it here. There is no vendored core/ to avoid; powershell/core/ is native pwsh config authored in this repo.
2. Don't hand-edit the mirrored assets. nvim/, starship/starship.toml and theme/palette.toml are synced from dotfiles-core (nvim-sync.ps1 / starship-sync.ps1 / theme-sync.ps1) — fix drift upstream, then re-sync, so the parity gate stays green.
3. Don't hand-edit a colour. Every hex in powershell/core/ and psmux/ that sits inside a # core:theme:gen marker — and every colour in the Tokyo Night scheme in windows-terminal/settings.json — is rendered from theme/palette.toml by gen-theme.ps1; gen-theme.ps1 -Check fails the PR that edits one by hand. Picking a colour in Windows Terminal's Settings pane counts.
4. Green the gate. tests/Invoke-Validation.ps1 is the fast, dependency-free check; pwsh -NoProfile -File tests/Invoke-Tests.ps1 is the full gated suite (the exact command CI runs). .githooks/pre-commit and CI mirror both.

Full rules — including the ones that bite (ASCII-only bootstrap.ps1, the README hash pin, # provides:/# requires: contracts, app-owned settings.json) — are in CONTRIBUTING.md.

Bugs and ideas: open an issue. Security problems: please report them privately — see SECURITY.md.

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Garrett Allen - @gerrrrt - garrettallen2@gmail.com - LinkedIn

Project Link: dotgibson

(back to top)