# Stash User Guide

## Table of Contents
1. [Installation](#installation)
   - [Using Guix](#using-guix)
   - [Manual Installation](#manual-installation)
2. [Shell Configuration](#shell-configuration)
   - [Fish Shell](#fish-shell)
   - [Bash Shell](#bash-shell)
   - [Zsh Shell](#zsh-shell)
3. [Basic Usage](#basic-usage)
4. [Advanced Features](#advanced-features)
5. [Configuration](#configuration)
6. [Troubleshooting](#troubleshooting)

## Installation

### Using Guix

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

```sh
# 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:
   ```sh
   # 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:
   ```sh
   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`:
   ```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:
   ```fish
   ln -sf ~/.guix-profile/bin/stash ~/.local/bin/stash
   ```

### Bash Shell

Add to `~/.bashrc`:
```bash
# 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`:
```zsh
# 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:
   ```sh
   # Move a directory to backup location
   stash -s ~/Documents/notes -t ~/backup/notes
   ```

2. Recursive stashing:
   ```sh
   # Move entire config directory
   stash -s ~/.config -t ~/.dotfiles/config -r
   ```

3. Interactive mode:
   ```sh
   # 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