Stash

stash is a command-line utility written in Guile Scheme that helps organize your files by moving them to a target location and creating symbolic links (symlinks) in their original location. While it's great for managing dotfiles, it works with any directories you want to organize.

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

• 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

Usage

Stash offers several ways to organize your files:

1. Interactive Mode (easiest for beginners):

   # Move Pictures directory to a backup location
   guile -L . stash.scm --source ~/Pictures --interactive
   

2. Explicit Paths:

   # Move Documents to backup while keeping symlink
   guile -L . stash.scm --source ~/Documents/notes --target ~/backup/notes
   
   # Move project to code archive
   guile -L . stash.scm --source ~/projects/webapp --target ~/code/archive/webapp
   

3. Recursive Mode (for entire directory trees):

   # Archive entire projects directory
   guile -L . stash.scm --source ~/projects --target ~/archive/projects --recursive
   

4. Dot Syntax (after files are stashed):

   # Recreate symlink for previously stashed directory
   cd ~/backup/notes
   guile -L . stash.scm .
   

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.