# Stash User Guide

## Table of Contents

1. [Introduction](#introduction)
2. [Installation](#installation)
3. [Basic Concepts](#basic-concepts)
4. [Usage Patterns](#usage-patterns)
5. [Common Use Cases](#common-use-cases)
6. [Advanced Features](#advanced-features)
7. [Troubleshooting](#troubleshooting)
8. [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)

### Step-by-Step Installation

1. **Clone the Repository**:

   ```sh
   git clone https://codeberg.org/glenneth/stash.git
   cd stash
   ```

2. **Set Up Guile Load Path**:

   ```sh
   mkdir -p ~/.guile.d/site/3.0
   ln -s $(pwd)/modules/stash ~/.guile.d/site/3.0/
   ```

3. **Create Convenient Alias** (Optional):

   Add to your shell config (~/.bashrc or ~/.zshrc):

   ```sh
   alias stash="guile -L $(pwd) $(pwd)/stash.scm"
   ```

4. **Verify Installation**:

   ```sh
   stash --help
   ```

## 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

- Supports home directory expansion (~)
- Handles both absolute and relative paths
- Maintains directory structure in target location

### 2. Symlink Management

- Creates intermediate directories as needed
- Handles existing symlinks gracefully
- Preserves original file permissions

## Troubleshooting

### Common Issues and Solutions

1. **"Permission denied" errors**
   - Check file permissions in both source and target locations
   - Ensure you have write access to both directories

2. **"File exists" errors**
   - Remove existing symlinks or files before stashing
   - Move existing files manually if needed

3. **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
```

### Common Command Combinations

```sh
# Interactive stashing
stash -s ~/Documents -i

# Recursive stashing with explicit paths
stash -s ~/.config -t ~/.dotfiles/config -r

# Quick symlink creation
cd ~/.dotfiles/config && stash .
```