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

10 KiB
Raw Permalink Blame History

Stash User Guide - Enhanced GNU Stow Replacement

Table of Contents

  1. Introduction
  2. Installation
  3. Shell Configuration
  4. GNU Stow-like Features
  5. Traditional Stashing
  6. Restoration
  7. Intelligent Stashing
  8. Common Use Cases
  9. Advanced Features
  10. Configuration
  11. Troubleshooting
  12. Tips and Best Practices

Introduction

Stash is a powerful symlink management utility written in Guile Scheme that serves as an enhanced replacement for GNU Stow. It helps you organize your files by moving them to a target location while maintaining easy access through symbolic links. With intelligent stashing, restoration capabilities, and GNU Stow-like deployment features, it's perfect for managing dotfiles and any other directory organization needs.

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

GNU Stow-like Features

Stash provides enhanced GNU Stow replacement functionality with intelligent behavior and additional features.

Deploy Mode

Deploy mode (-d) allows you to batch deploy all packages from a dotfiles repository, similar to GNU Stow:

# Deploy all packages from current directory
cd ~/.dotfiles && stash -d

# Deploy all packages with explicit path
stash -d /path/to/dotfiles

How it works:

  • Scans the current directory for subdirectories (packages)
  • Creates symlinks from each package's contents to the home directory
  • Automatically handles directory structure creation
  • Skips system files like .git, README.md, etc.

Dot Syntax

The dot syntax (.) provides reverse symlinking - creating a symlink from the current directory back to its corresponding location in the home directory:

# From within a dotfiles package directory
cd ~/.dotfiles/shell
stash .
# Creates: ~/.shell -> ~/.dotfiles/shell

Use cases:

  • Quick reverse linking from dotfiles repo
  • Testing configurations before full deployment
  • Selective package activation

Package Management

Deploy specific packages by name:

# Deploy only the shell package
cd ~/.dotfiles && stash shell

# Deploy only the emacs package  
cd ~/.dotfiles && stash emacs

Package structure example:

~/.dotfiles/
├── shell/
│   ├── zshrc
│   └── bashrc
├── emacs/
│   ├── config.org
│   └── init.el
└── git/
    └── gitconfig

Restoration

Stash includes complete restoration capabilities with metadata tracking:

# Restore a specific file
stash -R -s ~/.files/config/app/config.yml

# Restore using metadata
stash -R -s /path/to/stashed/file

Features:

  • Each stashed file includes .stash-meta metadata
  • Metadata contains original path information
  • Automatic directory structure recreation
  • Safe restoration with conflict detection

Intelligent Stashing

Stash automatically detects existing symlinks and adapts its behavior:

File-level stashing: When a directory already contains symlinks, stash operates at the file level to avoid "symlink to symlink" issues.

Directory-level stashing: When no symlinks exist, stash can move entire directories.

# First file - directory level stashing
stash -s ~/.config/app/config.yml -t ~/.files

# Second file - detects existing symlink, uses file-level stashing  
stash -s ~/.config/app/theme.json -t ~/.files

Traditional Stashing

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

3. Ignore Patterns

  • Create .stashignore in source directory
  • Add patterns similar to .gitignore
*.tmp
.DS_Store
node_modules/

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