zow

A high-performance, drop-in replacement for GNU Stow written in Zig.

Overview

zow is a symlink farm manager. It manages distinct sets of software/data located in separate directories (e.g., ~/stow/vim) and makes them appear to be installed in a single directory tree (e.g., ~/).

Key Differences from GNU Stow:

• Speed: 2-5x faster operations.
• Portable: Single static binary (~320KB). No Perl dependency.
• Safe: Atomic planning phase prevents partial installs on conflict.
• Cross-Platform: Native support for Linux, macOS, and Windows.

Performance

zow is significantly faster than the original Perl implementation.

Operation (100 files)	GNU Stow	zow	Speedup
Stow	~29ms	~6ms	5x
Unstow	~27ms	~5ms	5x
Restow	~28ms	~12ms	2x

Benchmarks run on Apple M2, average of 10 runs with tree folding enabled.

Installation

Requirements: Zig 0.15.2+

git clone https://github.com/HEKPYTO/zow.git
cd zow
zig build -Doptimize=ReleaseFast
sudo cp zig-out/bin/zow /usr/local/bin/

Usage

Basic Operations

# Install (symlink) a package
zow -S <package>

# Uninstall (remove symlinks)
zow -D <package>

# Reinstall (prune dead links, add new ones)
zow -R <package>

Common Flags

Flag	Description
-d, --dir	Source stow directory (default: current dir)
-t, --target	Target directory (default: parent of stow dir)
-n, --simulate	Dry-run; show what would happen
-v	Verbose output (repeat for more detail: -v -v)
--adopt	Import existing target files into the package
--dotfiles	Treat dot-file in package as .file in target
--no-folding	Disable directory folding (force individual links)

Note on macOS: Use absolute paths for directories (e.g., /Users/me/stow) to avoid issues with /tmp vs /private/tmp symlinks.

Configuration

zow respects standard Stow configuration files.

1. Global Config: .stowrc (in current dir or $HOME)
   • Format: Command line flags (e.g., --ignore=\.DS_Store)
2. Ignore Lists: .stow-local-ignore (in package root)
   • Format: Regex patterns (e.g., .*\.swp)

Development

# Build
zig build

# Run Tests (Unit + Integration)
zig build test

# Run Benchmarks
zig build bench

Use as Library

Add to build.zig.zon and import in your code:

const zow = @import("zow");

pub fn main() !void {
    // ... allocator setup ...
    try zow.stowPackage(allocator, "vim", .{
        .target_dir = "/home/user",
        .stow_dir = "/home/user/dotfiles",
    });
}

License

GNU General Public License v3.0 (LICENSE)