stash/README.md

Stash - Enhanced GNU Stow Replacement

stash is a powerful command-line utility written in Guile Scheme that serves as an enhanced replacement for GNU Stow. It helps organize your files by moving them to a target location and creating symbolic links (symlinks) in their original location. With intelligent stashing, restoration capabilities, and GNU Stow-like deployment features, it's perfect for managing dotfiles and any other directory organization needs.

Installation

There are two ways to install Stash:

Method 1: Using Guix (Recommended)

# Install from the local package definition
guix package --install-from-file=minimal-package.scm

# Configure your shell environment:

# For Fish shell (add to ~/.config/fish/config.fish):
set -gx GUIX_PROFILE $HOME/.guix-profile
set -gx PATH $GUIX_PROFILE/bin $PATH

# For Bash (add to ~/.bashrc):
export GUIX_PROFILE="$HOME/.guix-profile"
. "$GUIX_PROFILE/etc/profile"

# For Zsh (add to ~/.zshrc):
export GUIX_PROFILE="$HOME/.guix-profile"
. "$GUIX_PROFILE/etc/profile"

Method 2: Manual Installation

1. Prerequisites:

   • Guile Scheme 3.0.9 or later
   • A Unix-like environment (Linux/macOS)

2. Installation Steps:

   # Clone the repository
   git clone https://github.com/yourusername/stash.git
   cd stash
   
   # Add to your ~/.guile load path
   mkdir -p ~/.guile.d/site/3.0
   ln -s $(pwd)/modules/stash ~/.guile.d/site/3.0/
   
   # Optional: Add a convenient alias to your shell config (~/.bashrc or ~/.zshrc)
   echo 'alias stash="guile -L $(pwd) $(pwd)/stash.scm"' >> ~/.bashrc
   source ~/.bashrc
   

3. Verify Installation:

   # Test if stash works
   stash --help
   

Shell Integration

After installation, you might want to ensure the stash command is easily accessible:

1. Using Guix Installation:

   • The command should be available after setting up your shell environment as shown above
   • If not, create a symbolic link: ln -sf ~/.guix-profile/bin/stash ~/.local/bin/stash

2. Using Manual Installation:

   • Add an alias to your shell config:

     # For Fish (in ~/.config/fish/config.fish):
     alias stash="guile -L /path/to/stash /path/to/stash/stash.scm"
     
     # For Bash/Zsh:
     alias stash='guile -L /path/to/stash /path/to/stash/stash.scm'
     

Key Features

GNU Stow Replacement Capabilities

• Deploy Mode: Batch deployment of all packages (stash -d)
• Package Deployment: Deploy specific packages (stash package-name)
• Dot Syntax: Reverse symlinking from current directory (stash .)
• Intelligent Stashing: Automatically detects existing symlinks and adapts behavior
• Restoration: Complete file restoration with metadata tracking (stash -R)

Core Functionality

• Flexible Usage: Works with any directories, not just config files
• Interactive Mode: Option to interactively specify target directory
• Recursive Processing: Can process entire directory trees
• Advanced Path Handling: Supports home directory expansion and relative paths
• Symlink Management: Creates and manages symlinks while maintaining directory structure
• Ignore Patterns: Supports local and global ignore patterns
• Metadata Tracking: Each stashed file includes restoration metadata

Usage

GNU Stow-like Deployment (Recommended)

# Deploy all packages from dotfiles repository
cd ~/.dotfiles && stash -d

# Deploy specific package
cd ~/.dotfiles && stash shell

# Using dot syntax (reverse symlinking)
cd ~/.dotfiles/shell && stash .

Traditional Stashing (File Organization)

# Stash individual files
stash -s ~/.zshrc -t ~/.files

# Stash with interactive target selection
stash -s ~/.config -i

# Recursive stashing
stash -s ~/.config -t ~/.files -r

Restoration

# Restore stashed files back to original locations
stash -R -s ~/.files/config/app/config.yml

Complete Dotfiles Workflow

# 1. Stash your configurations
stash -s ~/.zshrc -t ~/.files
stash -s ~/.config/app -t ~/.files

# 2. On a new machine, deploy everything
cd ~/.files && stash -d

# 3. If needed, restore individual files
stash -R -s ~/.files/config/app/config.yml

Common Use Cases

1. Organizing Dotfiles:

   # Move config files to dotfiles repo
   guile -L . stash.scm --source ~/.config --target ~/.dotfiles/config --recursive
   

2. Backing Up Documents:

   # Move documents to external drive
   guile -L . stash.scm --source ~/Documents --target /media/backup/docs --recursive
   

3. Project Organization:

   # Archive old project while keeping it accessible
   guile -L . stash.scm --source ~/projects/old-app --target ~/archive/projects/old-app
   

Path Handling

Stash handles various path formats:

• Absolute paths: /home/user/documents
• Relative paths: ../documents, ./notes
• Home directory: ~/documents
• Dot notation: ., ..

Ignore Patterns

Stash supports two types of ignore files:

• .stash-local-ignore: Directory-specific ignore patterns
• .stash-global-ignore: Global ignore patterns

Default ignore patterns:

• .git directories
• .stash-local-ignore files
• .DS_Store files

Project Structure

stash/
├── stash.scm              # Main entry point
├── modules/
│   └── stash/
│       ├── paths.scm      # Path handling
│       ├── tree.scm       # Tree operations
│       ├── package.scm    # Package management
│       ├── file-ops.scm   # File operations
│       ├── log.scm        # Logging
│       ├── conflict.scm   # Conflict resolution
│       ├── colors.scm     # Terminal colors
│       └── help.scm       # Help messages
├── README.md             # Project overview
├── USER-GUIDE.md         # Comprehensive user documentation
├── DEVLOG.md            # Development log
└── LICENSE              # GNU GPL v3

Dependencies

• Guile Scheme 3.0.9
• Standard Guile libraries

Development

See DEVLOG.md for detailed development history and recent changes.

License

stash is licensed under the GNU General Public License v3. See the LICENSE file for more information.