WinDots (Windows Dotfiles)

Opinionated, Windows only dotfiles with:

• XDG-style layout rooted at %USERPROFILE% ($HOME/.config is enforced)
• Symlink-only linking with minimal, scoped elevation
• Reproducible package provisioning via a single Winget manifest
• Central PowerShell profile (shared between all tools like Visual Studio Code, PowerShell 5.x, and PowerShell 7.x)

Table of Contents

• WinDots (Windows Dotfiles)
  • Table of Contents
  • Quick Start
  • What Bootstrap Does
  • Updating
  • Repository Layout
  • Winget Manifest
  • Audit & Self-Test
  • Revert Examples
  • PowerShell Profile
  • Extending
  • License

---

Quick Start

One‑liner

irm https://raw.githubusercontent.com/adityatrivedi/windots/main/bin/bootstrap.ps1 | iex

Already cloned / extracted:

./bin/bootstrap.ps1 -ElevateLink -Verify -Quiet

Show help / options:

./bin/bootstrap.ps1 -Help

Key bootstrap flags:

• -ElevateLink Elevate only if needed for symlink creation
• -Verify Run self-test at end
• -Quiet Suppress informational logs
• -WhatIf / -Verbose Standard PowerShell diagnostics where supported
• -Help (or -?) Show usage summary and exit

---

What Bootstrap Does

1. Detects / enables Developer Mode (only that step may elevate)
2. Verifies functional non-admin symlink capability (falls back to elevated link if permitted)
3. Normalizes environment (sets XDG_CONFIG_HOME, ensures consistent $HOME/.config)
4. Installs winget (App Installer) automatically if not already present
5. Installs Winget packages from manifest (idempotent, skip if already present)
6. Installs required PowerShell modules (PSReadLine, CompletionPredictor) in current user scope
7. Creates profile stubs that dot-source the central profile
8. Links repo .config/* into $HOME/.config/* via symbolic links

• Also ensures %USERPROFILE%\.gitconfig includes ~/.config/git/config so Git reads the XDG config

9. Runs optional verification (self-test.ps1) if -Verify
10. Provides audit tooling to detect drift later (audit.ps1)

---

Updating

One-liner users: Re-run the one-liner — it re-downloads the latest archive, overwrites ~/.dotfiles, and re-runs bootstrap (fully idempotent):

irm https://raw.githubusercontent.com/adityatrivedi/windots/main/bin/bootstrap.ps1 | iex

Clone users: Pull the latest changes and re-run bootstrap:

git pull && ./bin/bootstrap.ps1 -ElevateLink -Verify

---

Repository Layout

Path / Script	Purpose
bin/bootstrap.ps1	Orchestrates full setup; supports -ElevateLink -Verify -Quiet.
bin/install.ps1	Package installation from Winget manifest (including fonts).
bin/modules.ps1	Ensures required PS modules (current-user scope).
bin/link.ps1	Creates symlinks for all .config entries.
bin/profile-setup.ps1	Installs PowerShell profile stubs.
bin/self-test.ps1	Post-setup validation (symlink, packages, modules, profile).
bin/audit.ps1	Drift detection vs. manifest (JSON or table output).
bin/revert.ps1	Selective or full cleanup (-All, supports -WhatIf).
bin/wt-theme.ps1	Windows Terminal theme export/import.
bin/_common.ps1	Shared logging & helpers.
packages/windows-winget.json	Canonical package ID list.
packages/windows-terminal-theme.json	Exported Windows Terminal theme data.
.config/	Tool configuration directory (XDG-style).

---

Winget Manifest

Package manifest format supports both simple and extended entries:

[
  { "id": "PackageName" },
  { "id": "PackageName2", "scope": "machine" }
]

• Default scope is user (no elevation required)
• Specify "scope": "machine" for packages that require machine-level installation
• Edit windows-winget.json to add/remove packages
• Run ./bin/install.ps1 to install new packages
• Run ./bin/audit.ps1 to verify current state

---

Audit & Self-Test

Self-test highlights environment readiness. Audit focuses on package drift.

Audit outputs table or JSON (-Json) and exit codes:

• 0 OK
• 1 Drift / missing packages
• 2 Manifest or internal error

Examples:

./bin/self-test.ps1
./bin/audit.ps1
./bin/audit.ps1 -Json | Out-File audit.json

---

Revert Examples

Dry run everything:

.\bin\revert.ps1 -All -WhatIf

Actual cleanup:

.\bin\revert.ps1 -All

Selective (links only):

.\bin\revert.ps1 -RemoveLinks

---

PowerShell Profile

Central profile lives under .config\powershell\profile.ps1 and initializes:

• Environment: XDG_CONFIG_HOME, EDITOR, PAGER
• Utility binaries: starship, zoxide, eza, bat (if present)
• Prompt & completions: Starship, PSReadLine, prediction source
• Safe module import wrapper & profile reload helper

Profile stubs (Documents profiles) simply dot-source this central file and are removed by revert.ps1.

---

Extending

Add config: place under .config\<tool> → rerun .\bin\link.ps1 -Force.

Add package: modify manifest → run .\bin\install.ps1 → verify with .\bin\audit.ps1.

Add initialization logic: extend central profile with guarded Initialize-* functions (keep vendor init isolated & optional).

---

Windows Terminal Theme

Theme data (color schemes, UI themes, profile defaults for colorScheme and font) is stored in packages/windows-terminal-theme.json and applied automatically during bootstrap.

Export the theme from your current machine:

./bin/wt-theme.ps1 -Export

Import on another machine (also runs during bootstrap):

./bin/wt-theme.ps1 -Import

Revert (remove imported theme from Windows Terminal):

.\bin\revert.ps1 -RevertTheme

---

License

See LICENSE for full text.