docs: add comprehensive user guide

Add USER-GUIDE.md with detailed documentation covering: - Installation and setup - Basic concepts and usage patterns - Common use cases and examples - Advanced features - Troubleshooting and best practices
2024-12-06 08:57:25 +03:00 · 2024-12-06 08:57:25 +03:00 · 8c1523a403
parent db11c09f3a
commit 8c1523a403
1 changed files with 196 additions and 0 deletions
--- a/USER-GUIDE.md
+++ b/USER-GUIDE.md
@ -0,0 +1,196 @@
+# 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 .
+```