Windows Development Environment Setup

This guide documents the current maintained Windows contributor workflow for Indexly.

It replaces the old Windows Terminal customization page and aligns with the actual implementation in:

• dotfiles-windows for shell, terminal, package manager, and editor setup
• project-indexly/setup.ps1 for repo-specific dependencies and virtual environment setup

What This Setup Covers

Recommended Windows Flow

1. Start With Official Base Components

Recommended before you bootstrap:

• PowerShell 7
• Windows Terminal
• winget / App Installer

You can run the bootstrap from Windows PowerShell, but the bootstrap now attempts to install PowerShell 7 first and then relaunch itself under pwsh when available.

2. Get The Dotfiles Repo

Clone the dotfiles repository:

git clone https://github.com/kimsgent/dotfiles.git "$HOME\dotfiles"
Copy-Item -Recurse -Force "$HOME\dotfiles\dotfiles-windows" "$HOME\dotfiles-windows"
Set-Location "$HOME\dotfiles-windows"

If git is not installed yet, install it first with an official source such as winget:

winget install --id Git.Git -e

3. Run The Maintained Windows Bootstrap

.\bootstrap.ps1

The current bootstrap flow does all of the following:

1. Ensures PowerShell 7 is available.
2. Relaunches the bootstrap under pwsh when possible.
3. Installs base Windows packages with winget.
4. Installs Scoop if missing.
5. Ensures Scoop Git support before adding buckets.
6. Adds and refreshes the extras and nerd-fonts buckets when available.
7. Installs core CLI tools such as neovim, ripgrep, fd, fzf, bat, eza, zoxide, jq, and delta.
8. Installs Nerd Fonts when the nerd-fonts bucket is available.
9. Ensures Python and Node.js are available.
10. Installs maintained PowerShell modules such as PSReadLine, PSFzf, Terminal-Icons, PSWindowsUpdate, and ImportExcel.
11. Copies the maintained PowerShell profile and links Starship and Neovim config.

4. Restart The Shell And Verify

Close the current shell and open a new PowerShell 7 session.

Run these checks:

pwsh --version
git --version
python --version
nvim --version
rg --version
fd --version

If the profile loaded correctly, you should also have helper commands such as:

usp
update-powershell
setup-env
dev-mode
minimal-mode

What The Windows Bootstrap Installs

Managed By winget

The current bootstrap uses winget for Windows-native packages such as:

• Microsoft.PowerShell
• Microsoft.WindowsTerminal
• JanDeDobbeleer.OhMyPosh
• Starship.Starship
• Microsoft.PowerToys
• OpenJS.NodeJS
• Python when no working Python runtime is already present

Managed By Scoop

The current bootstrap uses Scoop for CLI-focused tools and buckets. It currently installs or manages:

• git
• neovim
• ripgrep
• fd
• fzf
• bat
• eza
• zoxide
• jq
• delta
• fastfetch
• mingw

When the nerd-fonts bucket is available, it also installs:

• Hack-NF
• Meslo-NF

Managed By PowerShell Gallery

The bootstrap also installs or updates PowerShell modules that improve the contributor shell experience:

• PackageManagement
• PSReadLine
• PSFzf
• Terminal-Icons
• PSWindowsUpdate
• ImportExcel

Onboard The project-indexly Repository

After your workstation bootstrap is complete, move to the repo itself:

Set-Location D:\project-indexly

The repo contains its own onboarding script:

.\setup.ps1 -CheckOnly
.\setup.ps1

What setup.ps1 does today:

• validates winget, Python, and repo files
• applies system packages from winget.yaml
• creates or reuses .venv
• upgrades pip, setuptools, and wheel
• installs requirements.txt
• installs requirements-dev.txt

Supported modes:

.\setup.ps1 -CheckOnly
.\setup.ps1 -UpdateOnly
.\setup.ps1 -FreshInstall
.\setup.ps1 -Purge

If your dotfiles profile is already loaded, the same repo-native flow is also available through the helper command:

setup-env indexly -check
setup-env indexly

Recommended Validation For Contributors

After bootstrap and repo setup, verify the environment that actually matters for Indexly work:

Set-Location D:\project-indexly
.venv\Scripts\Activate.ps1
python -m indexly --help
indexly --version
indexly show-help
indexly doctor
pytest -q

If you are working on optional features, install the matching extra groups described in Install Indexly and Indexly Developer Guide.

Optional Quality-Of-Life Commands

The maintained Windows profile adds several useful commands for contributors:

Troubleshooting

Bootstrap Started In Windows PowerShell Instead Of PowerShell 7

This is expected on a clean machine.

The current bootstrap attempts to install PowerShell 7 first, then relaunches itself under pwsh. If it cannot, it continues with a warning and you can verify later with:

pwsh --version
update-powershell

Scoop Says Git Is Required For Buckets

The maintained bootstrap now installs or detects Scoop Git support before adding buckets.

If you still see bucket-related Git errors:

git --version
scoop update
usp

If git is still missing in the current session, restart PowerShell and rerun the bootstrap.

Scoop Cannot Find Hack-NF Or Meslo-NF

This usually means the nerd-fonts bucket is unavailable or stale, not that the fonts are universally unsupported.

Use this order:

scoop bucket list
scoop update
usp

If the nerd-fonts bucket is still missing, rerun the bootstrap after Git and Scoop are healthy.

Bootstrap Runs Without Administrator Rights

A non-elevated run is acceptable for most of the environment.

Current behavior:

• file symlinks may fall back to hard links or file copies
• Neovim directory linking may fall back to a junction
• some Windows Update or package operations may still require an elevated shell

Typical admin-sensitive areas:

• PSWindowsUpdate operations
• some winget installs or configuration changes
• symbolic links when Developer Mode is not enabled

setup.ps1 Fails During winget configure

project-indexly/setup.ps1 applies winget.yaml, and some packages may prompt, fail, or require elevation depending on machine policy.

Start with:

.\setup.ps1 -CheckOnly

Then rerun the full setup in an elevated shell if winget or package policy blocks the import.

Script Execution Is Blocked

If PowerShell blocks local scripts, use a per-user policy:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Related Pages

• Linux Development Environment Setup
• Install Indexly
• Indexly Developer Guide