glenn
/
stash
mirror of https://codeberg.org/glenneth/stash.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
stash/USER_GUIDE.md

8.0 KiB
Raw Permalink Blame History

Stash User Guide

Table of Contents

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

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

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

    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:

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

    ln -sf ~/.guix-profile/bin/stash ~/.local/bin/stash

Bash Shell

Add to ~/.bashrc:

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

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

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

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

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