stash/USER_GUIDE.md

# Stash User Guide

## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
   - [Using Guix](#using-guix)
   - [Manual Installation](#manual-installation)
3. [Shell Configuration](#shell-configuration)
   - [Fish Shell](#fish-shell)
   - [Bash Shell](#bash-shell)
   - [Zsh Shell](#zsh-shell)
4. [Basic Concepts](#basic-concepts)
5. [Usage Patterns](#usage-patterns)
6. [Common Use Cases](#common-use-cases)
7. [Advanced Features](#advanced-features)
8. [Configuration](#configuration)
9. [Troubleshooting](#troubleshooting)
10. [Tips and Best Practices](#tips-and-best-practices)

## Introduction

Stash is a powerful symlink management utility that helps you organize your files by moving them to a target location while maintaining easy access through symbolic links. While it's excellent for managing dotfiles, Stash can organize any type of files or directories.

### Why Use Stash?

- **Keep Your Files Organized**: Move files to logical storage locations while maintaining easy access
- **Backup with Access**: Store files in backup locations without changing your workflow
- **Dotfile Management**: Perfect for managing configuration files across different machines
- **Project Organization**: Archive old projects while keeping them accessible
- **Cross-device File Management**: Safely manage files across different storage devices

## Installation

### Prerequisites

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

### 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://codeberg.org/glenneth/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 Concepts

### How Stash Works

1. **Source Directory**: The original location of your files
2. **Target Directory**: Where you want to store the files
3. **Symbolic Links**: Created in the source location, pointing to the target

### Key Terms

- **Stashing**: The process of moving files to a target location and creating symlinks
- **Dot Syntax**: A shorthand way to create symlinks for previously stashed files
- **Recursive Mode**: Processing entire directory trees

## Usage Patterns

### 1. Interactive Mode

Best for beginners or when you want to choose the target location interactively.

```sh
stash --source ~/Pictures --interactive
```

### 2. Explicit Paths

When you know exactly where you want to store files.

```sh
stash --source ~/Documents/notes --target ~/backup/notes
```

### 3. Dot Syntax

Quick way to create symlinks for previously stashed files.

```sh
cd ~/.dotfiles/config/nvim
stash .    # Creates symlink in ~/.config/nvim
```

### 4. Recursive Mode

For processing entire directory trees.

```sh
stash --source ~/.config --target ~/.dotfiles/config --recursive
```

## Common Use Cases

### 1. Managing Dotfiles

Keep configuration files in a git repository:

```sh
# Initial stash
stash --source ~/.config/nvim --target ~/.dotfiles/config/nvim

# Later, on another machine
cd ~/.dotfiles/config/nvim
stash .
```

### 2. Project Organization

Archive old projects while keeping them accessible:

```sh
stash --source ~/projects/old-webapp --target ~/archive/projects/webapp
```

### 3. Cross-device File Management

Store large files on external drives:

```sh
stash --source ~/Videos --target /media/external/videos --recursive
```

## Advanced Features

### 1. Path Handling

Stash provides robust path handling capabilities:

- Supports home directory expansion (`~`)
- Handles relative paths intelligently
- Normalizes paths for consistent comparison
- Resolves symbolic links when needed
- Maintains proper path relationships in recursive operations

The path normalization ensures that:
- Redundant path separators are removed
- Parent directory references (`..`) are resolved
- Current directory references (`.`) are removed
- Paths are made relative when appropriate
- Symlinks are handled correctly in comparisons

### 2. Directory Tree Operations

Stash includes sophisticated directory tree handling:

- Recursive directory scanning
- Efficient tree traversal
- Intelligent ignore patterns (e.g., `.git/`, `*.bak`)
- Proper symlink planning and creation
- Conflict detection and resolution

The tree operations ensure:
- All file relationships are preserved
- Circular symlinks are prevented
- Existing symlinks are handled appropriately
- Conflicts are detected early
- Directory structures are maintained

### 3. Conflict Resolution

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

## Configuration

### Environment Variables

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

### Global Configuration

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

## Troubleshooting

### Common Issues and Solutions

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

### Cross-device Issues

- Use the recursive flag for cross-device operations
- Ensure target location has sufficient space

## Tips and Best Practices

1. **Organization**

   - Keep related files together in the target location
   - Use meaningful directory names
   - Document your stash organization

2. **Backup**

   - Always back up important files before stashing
   - Test symlinks after creation
   - Use version control for dotfiles

3. **Maintenance**

   - Regularly check for broken symlinks
   - Keep your stash locations organized
   - Document your stash structure

## Command Reference

### Basic Commands

```sh
stash --help                 # Display help
stash --version             # Show version
stash --source DIR          # Specify source directory
stash --target DIR          # Specify target directory
stash --recursive           # Process directories recursively
stash --interactive         # Interactive target selection
```

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