stash/USER-GUIDE.md

Stash User Guide

Table of Contents

1. Introduction
2. Installation
3. Basic Concepts
4. Usage Patterns
5. Common Use Cases
6. Advanced Features
7. Troubleshooting
8. 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:

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

2. Set Up Guile Load Path:

   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):

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

4. Verify Installation:

   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.

stash --source ~/Pictures --interactive

2. Explicit Paths

When you know exactly where you want to store files.

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

3. Dot Syntax

Quick way to create symlinks for previously stashed files.

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

4. Recursive Mode

For processing entire directory trees.

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

Common Use Cases

1. Managing Dotfiles

Keep configuration files in a git repository:

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

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

3. Cross-device File Management

Store large files on external drives:

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

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

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