stash/USER_GUIDE.md

Stash User Guide

Table of Contents

1. Installation
   • Using Guix
   • Manual Installation
2. Shell Configuration
   • Fish Shell
   • Bash Shell
   • Zsh Shell
3. Basic Usage
4. Advanced Features
5. Configuration
6. Troubleshooting

Installation

Using Guix

The recommended way to install Stash is using the Guix package manager:

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

After installation, the stash executable will be available in your Guix profile at ~/.guix-profile/bin/stash.

Manual Installation

If you're not using Guix, you can install Stash manually:

1. Install prerequisites:

   # Debian/Ubuntu
   sudo apt-get install guile-3.0
   
   # Fedora
   sudo dnf install guile30
   
   # Arch Linux
   sudo pacman -S guile
   

2. Clone and set up the repository:

   git clone https://github.com/yourusername/stash.git
   cd stash
   mkdir -p ~/.guile.d/site/3.0
   ln -s $(pwd)/modules/stash ~/.guile.d/site/3.0/
   

Shell Configuration

Fish Shell

1. Add to ~/.config/fish/config.fish:

   # Guix environment setup
   set -gx GUIX_PROFILE $HOME/.guix-profile
   set -gx PATH $GUIX_PROFILE/bin $PATH
   
   # Load Guix environment variables
   if test -f $GUIX_PROFILE/etc/profile
       for line in (cat $GUIX_PROFILE/etc/profile | grep '^export' | string replace 'export ' '')
           set var (string split '=' $line)
           set -gx $var[1] (eval echo $var[2])
       end
   end
   

2. Alternative method using symlink:

   ln -sf ~/.guix-profile/bin/stash ~/.local/bin/stash
   

Bash Shell

Add to ~/.bashrc:

# Guix environment setup
export GUIX_PROFILE="$HOME/.guix-profile"
if [ -f "$GUIX_PROFILE/etc/profile" ]; then
    . "$GUIX_PROFILE/etc/profile"
fi

Zsh Shell

Add to ~/.zshrc:

# Guix environment setup
export GUIX_PROFILE="$HOME/.guix-profile"
if [ -f "$GUIX_PROFILE/etc/profile" ]; then
    . "$GUIX_PROFILE/etc/profile"
fi

Basic Usage

1. Simple file stashing:

   # Move a directory to backup location
   stash -s ~/Documents/notes -t ~/backup/notes
   

2. Recursive stashing:

   # Move entire config directory
   stash -s ~/.config -t ~/.dotfiles/config -r
   

3. Interactive mode:

   # Let stash prompt for target location
   stash -s ~/Pictures -i
   

Advanced Features

1. Ignore Patterns

   • Create .stashignore in source directory
   • Add patterns similar to .gitignore

   *.tmp
   .DS_Store
   node_modules/
   

2. Recursive Mode

   • Use -r flag for entire directory trees
   • Preserves directory structure
   • Creates symlinks for all subdirectories

3. Conflict Resolution

   • Automatically detects existing files/symlinks
   • Interactive prompts for resolution
   • Options to skip, replace, or backup

Configuration

1. Environment Variables

   • GUILE_AUTO_COMPILE=0: Disable auto-compilation
   • GUILE_LOAD_PATH: Add custom module paths
   • GUIX_PROFILE: Set Guix profile location

2. Global Configuration

   • System-wide ignore patterns in /etc/stash/ignore
   • User-specific patterns in ~/.config/stash/ignore

Troubleshooting

1. Command Not Found

   • Verify Guix profile is sourced correctly
   • Check PATH includes ~/.guix-profile/bin
   • Try creating symlink in ~/.local/bin

2. Module Loading Issues

   • Ensure GUILE_LOAD_PATH includes module directory
   • Check module permissions and ownership
   • Verify Guile version compatibility

3. Permission Errors

   • Check file/directory permissions
   • Ensure write access to target location
   • Verify symlink creation permissions

4. Common Warnings

   • "canonicalize-path override": Normal, can be ignored
   • "auto-compilation enabled": Set GUILE_AUTO_COMPILE=0

For more information or to report issues, visit: https://codeberg.org/glenneth/stash