🐰 Stowbun

Manage your dotfiles easily with GNU Stow and Git

Stowbun is a lightweight bash script that simplifies managing your dotfiles using GNU Stow and Git. It provides a clean interface for organizing, syncing, and deploying your configuration files across machines.

  (\___/)
  (='.'=)   Stowbun
  (")_(")     by Zenny
 ~~|   |~~
   '---'    Manage your dotfiles easily.

Features

• Symlink Management: Uses GNU Stow for reliable symlink creation
• Git Integration: Push and pull dotfiles to/from remote repositories
• Package Organization: Automatically organizes files into logical packages
• Colorized Output: Clear, color-coded terminal feedback (respects NO_COLOR)
• Simple Commands: Intuitive command-line interface with short aliases
• Quick Setup: Initialize from existing Git repositories
• Smart Listing: List all managed files or filter by specific folders
• Force Reload: Override conflicting files when needed

Requirements

• git - Version control
• stow - Symlink management tool
• Bash 4.0+ (for associative arrays)

Installation

1. Download the script:

curl -O https://quelloffen.ch/zenn/stowbun/raw/branch/main/stowbun
# or
wget https://quelloffen.ch/zenn/stowbun/raw/branch/main/stowbun

2. Make it executable:

chmod +x stowbun

3. Move to your PATH:

mv stuwbun ~/.local/bin/
# or
sudo mv stowbun /usr/local/bin/

Or create an alias in your shell config:

alias stowbun='/path/to/stowbun'

Quick Start

# Initialize from a Git repository
stowbun init git@github.com:username/dotfiles.git

# Add a configuration file
stowbun add ~/.config/nvim

# Apply changes
stowbun reload

# Force apply (override conflicts)
stowbun force-reload

# List managed files
stowbun list

# Push changes to repository
stowbun push "Updated nvim config"

Commands

init (alias: i)

Initialize a new dotfiles repository by cloning from Git.

stowbun init <repository-url>
stowbun i git@github.com:user/dotfiles.git

add (alias: a)

Add a file or folder to your dotfiles. The script will:

• Move the file to the dotfiles directory
• Organize it into the appropriate package structure
• Create a symlink back to the original location

stowbun add <path>
stowbun add ~/.config/nvim
stowbun add ~/.bashrc
stowbun a ~/.zshrc

Features:

• Automatically normalizes paths (relative or absolute)
• Resolves symlinks to their targets
• Confirms before moving files
• Immediately applies stow after adding

reload (alias: r)

Apply all dotfiles by running stow on all packages. This creates/updates symlinks for all packages in your dotfiles directory.

stowbun reload
stowbun r

Stowbun will iterate through all directories in ~/.dotfiles/ and apply them with GNU Stow.

force-reload (alias: fr)

Force apply dotfiles by adopting existing files and then restoring from Git. This is useful when you have conflicts and want to override your local home directory files with the versions from your dotfiles repository.

stowbun force-reload
stowbun fr

Warning: This command will:

1. Adopt (overwrite) existing files in your dotfiles directory with versions from your home directory
2. Immediately restore the original versions from Git, effectively replacing your home directory files

Use this when you want to forcefully apply your dotfiles and override any conflicting files in your home directory.

list (alias: l)

List all managed files organized by package. Optionally filter by a specific folder.

stowbun list              # List all managed files
stowbun list .config      # List only .config files
stowbun l .local          # List only .local files

push (alias: ps)

Commit and push changes to the Git repository.

stowbun push                      # Auto-generate commit message
stowbun push "Updated configs"    # Custom commit message
stowbun ps "Added kitty theme"    # Using short alias

Auto-commit message: If no message is provided, Stowbun generates one from modified package names.

pull (alias: pl)

Pull changes from the remote repository.

stowbun pull
stowbun pl

status (alias: s)

Display Stowbun status including:

• Git version
• Stow version
• Dotfiles directory location and status

stowbun status
stowbun s

help (alias: h)

Show usage information and examples.

stowbun help
stowbun h

Configuration

Stowbun uses environment variables for configuration:

Variable	Default	Description
STOWMAN_DOTDIR	~/.dotfiles	Dotfiles directory location
STOWMAN_HOMEDIR	~	Target directory for symlinks
NO_COLOR	(unset)	Set to any value to disable colored output

Example configuration:

# In your ~/.bashrc or ~/.zshrc
export STOWMAN_DOTDIR="$HOME/my-dotfiles"
export STOWMAN_HOMEDIR="$HOME"

How It Works

Package Structure

Stowbun organizes your dotfiles into packages within ~/.dotfiles/. Each top-level directory is treated as a package:

~/.dotfiles/
├── .git/                    # Git repository
├── .config/
│   ├── nvim/
│   │   └── init.vim
│   ├── kitty/
│   │   └── kitty.conf
│   └── tmux/
│       └── tmux.conf
├── .local/
│   └── bin/
│       └── custom-script.sh
└── bash/
    ├── .bashrc
    └── .bash_profile

Symlink Management

GNU Stow creates symlinks from your home directory to the dotfiles:

~ (Home)                     ~/.dotfiles/ (Source)
├── .config/                 ├── .config/
│   └── nvim/ → (symlink)    │   └── nvim/ (actual files)
├── .bashrc → (symlink)      └── bash/
                                └── .bashrc (actual file)

Git Synchronization

All changes are version-controlled and can be synced across machines:

• Push: Commits and pushes local changes
• Pull: Fetches and merges remote changes
• Automatic commit messages: Generated from changed packages

Typical Workflow

1. First Time Setup

On your first machine:

# Clone your existing dotfiles
stowbun init git@github.com:user/dotfiles.git

# Apply all dotfiles
stowbun reload

2. Adding New Configurations

# Add a new config file
stowbun add ~/.config/alacritty

# Confirm the operation
# Continue [Y/n] y

# Push to Git
stowbun push "Added alacritty config"

3. Syncing Across Machines

On a new machine:

# Clone and setup
stowbun init git@github.com:user/dotfiles.git
stowbun reload

On an existing machine:

# Get latest changes
stowbun pull
stowbun reload

4. Making Changes

# Edit your configs normally (they're symlinked)
vim ~/.config/nvim/init.vim

# View what changed
cd ~/.dotfiles && git status

# Commit and push
stowbun push "Updated nvim keybindings"

5. Reviewing Your Setup

# See what's managed
stowbun list

# Check specific folder
stowbun list .config

# Check system status
stowbun status

Advanced Usage

Ignoring Files

Create .stow-local-ignore in your dotfiles directory to exclude files from being stowed:

\.git
\.gitignore
^/README\.md
^/LICENSE
\.DS_Store

Custom Dotfiles Location

# Use a different directory
export STOWMAN_DOTDIR="$HOME/configs"
stowbun init git@github.com:user/configs.git

Troubleshooting

Missing Dependencies

Install git and stow using your package manager:

# macOS
brew install git stow

# Ubuntu/Debian
sudo apt install git stow

# Arch Linux
sudo pacman -S git stow

# Fedora
sudo dnf install git stow

Stow Conflicts

If stow reports conflicts:

# Error: existing target is not owned by stow

Solution 1: Back up or remove existing files before stowing:

# Backup existing config
mv ~/.config/nvim ~/.config/nvim.backup

# Then reload
stowbun reload

Solution 2: Use force-reload to override conflicts:

# This will adopt existing files and restore from Git
stowbun force-reload

Note: force-reload will replace your home directory files with versions from your dotfiles repository. Make sure you've committed any important changes first!

Git Not Initialized

# Error: Not a git repository

Solution: Initialize first:

stowbun init git@github.com:user/dotfiles.git

File Not in Home Directory

# Error: File must be in home directory

Solution: Stowbun only manages files in your home directory. Move the file to ~ first:

cp /etc/config ~/.config/myconfig
stowbun add ~/.config/myconfig

File Organization Examples

Example 1: Shell Configuration

~/.dotfiles/
├── .bashrc
├── .bash_profile
├── .zshrc
└── .zprofile

Example 2: Editor Configuration

~/.dotfiles/
└── .config/
    ├── nvim/
    │   ├── init.vim
    │   └── lua/
    ├── vim/
    │   └── .vimrc
    └── emacs/
        └── init.el

Example 3: Development Tools

~/.dotfiles/
└── .local/
    ├── bin/
    │   ├── custom-script.sh
    │   └── dev-tools.py
    └── share/
        └── templates/

Credits

License

This script is provided as-is. Feel free to modify and distribute.

---

Have a nice day!