wingetCollections
  • Auto
  • Search
  • Awesome Collections
  • Awesome Programs
  • My Favorite Collections
  • My Collections
  • Account / Settings
  • Terms of Service
  • Privacy
  • About

© 2025 winget.ragerworks.com

Loading...
Install Winstow using Winget - wingetCollections
  1. Go back
  2. Packages
  3. Winstow
Winstow logo

Winstow MathiasCodes

configuration dotfile-manager dotfiles stow symlink symlink-manager windows
Use this command to install Winstow:
winget install --id=MathiasCodes.Winstow -e

Winstow is a Windows-native symlink farm manager inspired by GNU Stow. It helps you manage your dotfiles, configuration files, and software packages by creating symbolic links from a central stow directory to a target directory (typically your home directory).

Key Features:

  • Windows-Native: Built specifically for Windows with proper symlink support.
  • GNU Stow Compatible: Familiar interface if you've used GNU Stow.
  • Directory Folding: Intelligent directory symlinking reduces the number of links needed.
  • Conflict Resolution: Offers --adopt and --override options to handle existing files during stow or restow operations.
  • Pattern Matching: Use --ignore and --defer for flexible file management, allowing you to skip certain files or defer conflicts.
  • Configuration File Support: Set defaults using a .winstowrc configuration file.
  • Small & Fast: A single ~600KB binary ensures quick performance.
  • Safe Operations: Includes dry-run mode to preview changes before applying them.

Audience & Benefit: Ideal for Windows users managing dotfiles, configuration files, or software packages. Winstow enables efficient organization and management of files without cluttering your target directory. It allows you to update configurations easily and provides safe operations with conflict resolution options, ensuring that file management remains predictable and controlled.

Winstow can be installed via winget when it becomes available through package managers like Scoop or WinGet.

README

Winstow

License: MIT

Winstow is a Windows-native symlink farm manager inspired by GNU Stow. It helps you manage your dotfiles, configuration files, and software packages by creating symbolic links from a central stow directory to a target directory (typically your home directory).

Disclaimer

I created Winstow to replicate my GNU Stow dotfile management workflow from Linux on Windows - keeping all my configuration files in a single git repository and symlinking them as needed.

⚠️ Note: Winstow is currently in active development and may be unstable. The API is subject to change without prior notice. Please use it with caution and make backups of your files before using it.

I'm still learning Rust, so the code may not be the most idiomatic or efficient. Suggestions for improvement are welcome.

⚠️ Winstow is not a 1:1 port of GNU Stow and does not guarantee identical range of functionality or behavior.

Why Winstow?

  • ✅ Windows-Native: Built specifically for Windows with proper symlink support
  • ✅ GNU Stow Compatible: Familiar interface if you've used GNU Stow
  • ✅ Directory Folding: Intelligent directory symlinking reduces link count
  • ✅ Conflict Resolution: --adopt and --override for handling existing files
  • ✅ Pattern Matching: --ignore and --defer for flexible file management
  • ✅ Configuration Files: Set defaults with .winstowrc
  • ✅ Small & Fast: Single ~600KB binary
  • ✅ Safe: Dry-run mode to preview changes before applying

Prerequisites

To create symbolic links on Windows, you need one of the following:

  1. Developer Mode enabled (Windows 10/11) - Recommended

    • Settings → Update & Security → For developers → Developer Mode

  2. Administrator privileges

    • Run winstow from an elevated command prompt

Installation

Option 1: Download Binary

Download the latest release from and add it to your PATH.

Versions
0.3.0
Website
github.com
License
Last updated
11/18/2025
Download latest version
GitHub Releases

Option 2: Build from Source

# Clone the repository
git clone https://github.com/MathiasCodes/winstow.git
cd winstow

# Build release binary
cargo build --release

# Binary will be at target/release/winstow.exe

Option 3: Package Managers (Coming Soon)

# Scoop
scoop install winstow

# WinGet
winget install winstow

Quick Start

Basic Usage

# Stow a package (create symlinks)
winstow mypackage

# Unstow a package (remove symlinks)
winstow -D mypackage

# Restow a package (refresh symlinks)
winstow -R mypackage

# Dry-run to see what would happen
winstow -n mypackage

# Verbose output
winstow -v mypackage

Directory Structure

# Stow directory (contains all your dotfile packages)
C:\Users\USER\Dotfiles\
  ├── Git\
  │   └── .gitconfig
  ├── Git-Bash\
  │   ├── .bashrc
  │   └── .inputrc
  └── lazygit\
      └── AppData\
          └── Local\
              └── lazygit\
                  └── config.yaml

# Target directory (where symlinks are created, typically your home directory)
# Note: lazygit uses directory folding - a single directory symlink instead of individual file symlinks
C:\Users\USER\
  ├── .gitconfig -> C:\Users\USER\Dotfiles\Git\.gitconfig
  ├── .bashrc -> C:\Users\USER\Dotfiles\Git-Bash\.bashrc
  ├── .inputrc -> C:\Users\USER\Dotfiles\Git-Bash\.inputrc
  └── AppData\
      └── Local\
          └── lazygit -> C:\Users\USER\Dotfiles\lazygit\AppData\Local\lazygit

Command-Line Interface

Actions

FlagLong FormDescription
-S (optional)--stowStow packages (default action)
-D--deleteUnstow (delete) packages
-R--restowRestow packages (unstow then stow)

Options

FlagLong FormDescription
-d DIR--dir DIRStow directory (default: current directory)
-t DIR--target DIRTarget directory (default: home directory)
-v--verboseEnable verbose output
-n--dry-runPreview changes without applying them
--adoptMove conflicting files into package (stow/restow only)
--overrideRemove conflicting files (stow/restow only, destructive)
--ignore PATTERNSkip files matching pattern (stow/restow only)
--defer PATTERNSkip files matching pattern if they already exist in target (stow/restow only)
-h--helpShow help message
-V--versionShow version

Examples

Managing Dotfiles

PowerShell:

# Set up your stow directory
mkdir $env:USERPROFILE\Dotfiles
cd $env:USERPROFILE\Dotfiles
mkdir Git
mkdir Git-Bash

# Move your dotfiles into the packages
move $env:USERPROFILE\.gitconfig Git\
move $env:USERPROFILE\.bashrc Git-Bash\
move $env:USERPROFILE\.inputrc Git-Bash\

# Stow the packages
winstow -d $env:USERPROFILE\Dotfiles -t $env:USERPROFILE Git
winstow -d $env:USERPROFILE\Dotfiles -t $env:USERPROFILE Git-Bash

# Now .gitconfig, .bashrc, and .inputrc are symlinks to your Dotfiles packages

Git Bash:

# Set up your stow directory
mkdir -p $USERPROFILE/Dotfiles
cd $USERPROFILE/Dotfiles
mkdir Git
mkdir Git-Bash

# Move your dotfiles into the packages
mv $USERPROFILE/.gitconfig Git/
mv $USERPROFILE/.bashrc Git-Bash/
mv $USERPROFILE/.inputrc Git-Bash/

# Stow the packages
winstow -d $USERPROFILE/Dotfiles -t $USERPROFILE Git
winstow -d $USERPROFILE/Dotfiles -t $USERPROFILE Git-Bash

# Now .gitconfig, .bashrc, and .inputrc are symlinks to your Dotfiles packages

Handling Conflicts

# If files already exist in target, you'll get an error
winstow mypackage
# Error: Conflict: C:\Users\You\.gitconfig already exists

# Option 1: Adopt the existing file into the package
winstow --adopt mypackage
# Moves .gitconfig into mypackage/, then creates symlink

# Option 2: Override (remove) the existing file
winstow --override mypackage
# Removes .gitconfig, then creates symlink (destructive!)

Using Ignore and Defer Patterns

# Ignore backup files and OS metadata (always skip these)
winstow --ignore "*.bak" --ignore ".DS_Store" --ignore "Thumbs.db" mypackage

# Ignore entire directories
winstow --ignore "node_modules" mypackage

# Defer allows another package to manage shared files
# If .bashrc already exists, skip it; otherwise, stow it
winstow --defer ".bashrc" package-a

# Later, package-b can manage .bashrc
winstow package-b  # This will stow .bashrc from package-b

Difference between --ignore and --defer:

  • --ignore: Always skip files matching the pattern (e.g., temporary files, build artifacts)
  • --defer: Skip files matching the pattern only if they already exist in the target directory (useful for shared configuration files managed by different packages)

Restowing After Updates

PowerShell:

# After updating your dotfiles repository
cd $env:USERPROFILE\Dotfiles
git pull

# Refresh symlinks
winstow -R -d $env:USERPROFILE\Dotfiles -t $env:USERPROFILE Git

Git Bash:

# After updating your dotfiles repository
cd $USERPROFILE/Dotfiles
git pull

# Refresh symlinks
winstow -R -d $USERPROFILE/Dotfiles -t $USERPROFILE Git

Dry-Run Mode

PowerShell:

# See what would happen without making changes
winstow -n -v Git

# Output:
# === DRY RUN MODE - No changes will be made ===
# [DRY RUN] Create file link: .gitconfig -> ..\Dotfiles\Git\.gitconfig
# Would stow 1 package(s)

Git Bash:

# See what would happen without making changes
winstow -n -v Git

# Output:
# === DRY RUN MODE - No changes will be made ===
# [DRY RUN] Create file link: .gitconfig -> ..\Dotfiles\Git\.gitconfig
# Would stow 1 package(s)

Configuration File

Create a .winstowrc file in one of these locations:

  1. Current directory: ./.winstowrc
  2. Home directory: %USERPROFILE%\.winstowrc
  3. AppData: %APPDATA%\winstow\config.toml

Example Configuration

# Default stow directory
default-dir = "C:\\stow"

# Default target directory  
default-target = "C:\\Users\\YourName"

# Default ignore patterns
ignore = ["*.bak", ".DS_Store", "Thumbs.db", "desktop.ini"]

# Default defer patterns
defer = ["*.lock"]

# Enable verbose mode by default
verbose = false

CLI arguments always override config file settings.

Directory Folding

winstow implements directory folding (inspired by GNU Stow) for efficiency:

Folding (Creating a Single Directory Symlink)

# Package structure:
C:\Users\USER\Dotfiles\mypackage\AppData\Local\app\settings.json

# If C:\Users\USER\AppData\Local\app\ doesn't exist, winstow creates:
C:\Users\USER\AppData\Local\app -> C:\Users\USER\Dotfiles\mypackage\AppData\Local\app

Unfolding (Expanding When Needed)

# First package creates a directory symlink:
C:\Users\USER\AppData\Local -> C:\Users\USER\Dotfiles\package1\AppData\Local

# Second package needs different AppData\Local contents:
# winstow automatically unfolds:
C:\Users\USER\AppData\Local\
  ├── app1 -> C:\Users\USER\Dotfiles\package1\AppData\Local\app1
  └── app2 -> C:\Users\USER\Dotfiles\package2\AppData\Local\app2

Best Practices

  1. Always use -n first to preview changes before applying them
  2. Use -v for debugging to see detailed operations and understand what's happening
  3. Set up .winstowrc for common settings to avoid repeating command-line options
  4. Keep packages focused - one purpose per package (e.g., separate vim, git, bash packages)
  5. Test in a temp directory before applying to your real dotfiles
  6. Use version control (git) in your stow directory to track changes
  7. Document your packages with README files explaining what each package contains
  8. Backup before --override - this option is destructive and removes existing files!
  9. Backup before --adopt - this option is destructive and removes existing files!

Troubleshooting

"Permission denied" Error

Problem: Cannot create symbolic links

Solutions:

  1. Enable Developer Mode (Settings → For developers)
  2. Run as Administrator
  3. Check Windows version (requires Windows Vista+)

Symlinks Not Working

Problem: Symlinks appear as files or don't work

Check:

  • Developer Mode is enabled OR running as Administrator
  • Using proper Windows symlink support (not shortcuts)
  • Target files/directories exist

"Conflict" Error

Problem: Conflict: path already exists

Solutions:

# Option 1: Adopt existing file
winstow --adopt mypackage

# Option 2: Override existing file
winstow --override mypackage

# Option 3: Manually remove/backup the file
move conflicting-file conflicting-file.backup
winstow mypackage

Dry-Run Shows Different Results

Problem: Dry-run output doesn't match actual execution

Note: Dry-run simulates operations but doesn't account for all dynamic conditions. Always make sure you have a backup of your files.

Development

Building

# Development build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run tests including ignored ones (requires Developer Mode)
cargo test -- --ignored

Project Structure

winstow/
├── src/
│   ├── main.rs          # Entry point and CLI routing
│   ├── cli.rs           # Command-line argument parsing
│   ├── config.rs        # Configuration file handling
│   ├── error.rs         # Error types
│   ├── logger.rs        # Logging infrastructure
│   ├── path_utils.rs    # Path manipulation utilities
│   ├── fs_ops.rs        # Windows filesystem operations
│   ├── planner.rs       # Action planning and execution
│   ├── stow.rs          # Stow operation logic
│   ├── unstow.rs        # Unstow operation logic
│   ├── adopt.rs         # Adopt/override functionality
│   └── ignore.rs        # Pattern matching
├── tests/
│   └── integration_tests.rs  # Integration tests
├── docs/
│   └── TECHNICAL_CONCEPT.md  # Technical documentation
├── Cargo.toml
├── README.md
├── LICENSE
├── CHANGELOG.md
└── DISTRIBUTION.md

Testing

All tests use temporary directories and should be safe to run:

# All tests (unit + integration)
cargo test

# Just integration tests
cargo test --test integration_tests

# Test with output
cargo test -- --nocapture

# Tests requiring symlink creation (needs Developer Mode)
cargo test -- --ignored

Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

  • Inspired by GNU Stow by Bob Glickstein
  • Built with Rust
  • Uses clap for CLI parsing
  • Uses windows-rs for Windows API access
  • Uses thiserror for error handling
  • Uses serde for serialization/deserialization
  • Uses toml for configuration file parsing
  • Uses glob for pattern matching
  • Uses dirs for platform-specific directory paths

Support

  • 📖 Documentation
  • 🐛 Issue Tracker
  • 💬 Discussions