stash/README.md

# Stash - Enhanced GNU Stow Replacement

`stash` is a powerful command-line utility written in Guile Scheme that serves as an enhanced replacement for GNU Stow. It helps organize your files by moving them to a target location and creating symbolic links (symlinks) in their original location. With intelligent stashing, restoration capabilities, and GNU Stow-like deployment features, it's perfect for managing dotfiles and any other directory organization needs.

## Installation

There are two ways to install Stash:

### Method 1: Using Guix (Recommended)

```sh
# Install from the local package definition
guix package --install-from-file=minimal-package.scm

# Configure your shell environment:

# For Fish shell (add to ~/.config/fish/config.fish):
set -gx GUIX_PROFILE $HOME/.guix-profile
set -gx PATH $GUIX_PROFILE/bin $PATH

# For Bash (add to ~/.bashrc):
export GUIX_PROFILE="$HOME/.guix-profile"
. "$GUIX_PROFILE/etc/profile"

# For Zsh (add to ~/.zshrc):
export GUIX_PROFILE="$HOME/.guix-profile"
. "$GUIX_PROFILE/etc/profile"
```

### Method 2: Manual Installation

1. **Prerequisites**:
   - Guile Scheme 3.0.9 or later
   - A Unix-like environment (Linux/macOS)

2. **Installation Steps**:

   ```sh
   # Clone the repository
   git clone https://github.com/yourusername/stash.git
   cd stash

   # Add to your ~/.guile load path
   mkdir -p ~/.guile.d/site/3.0
   ln -s $(pwd)/modules/stash ~/.guile.d/site/3.0/

   # Optional: Add a convenient alias to your shell config (~/.bashrc or ~/.zshrc)
   echo 'alias stash="guile -L $(pwd) $(pwd)/stash.scm"' >> ~/.bashrc
   source ~/.bashrc
   ```

3. **Verify Installation**:

   ```sh
   # Test if stash works
   stash --help
   ```

## Shell Integration

After installation, you might want to ensure the `stash` command is easily accessible:

1. **Using Guix Installation**:
   - The command should be available after setting up your shell environment as shown above
   - If not, create a symbolic link: `ln -sf ~/.guix-profile/bin/stash ~/.local/bin/stash`

2. **Using Manual Installation**:

   - Add an alias to your shell config:

     ```sh
     # For Fish (in ~/.config/fish/config.fish):
     alias stash="guile -L /path/to/stash /path/to/stash/stash.scm"

     # For Bash/Zsh:
     alias stash='guile -L /path/to/stash /path/to/stash/stash.scm'
     ```

## Key Features

### GNU Stow Replacement Capabilities
- **Deploy Mode**: Batch deployment of all packages (`stash -d`)
- **Package Deployment**: Deploy specific packages (`stash package-name`)
- **Dot Syntax**: Reverse symlinking from current directory (`stash .`)
- **Intelligent Stashing**: Automatically detects existing symlinks and adapts behavior
- **Restoration**: Complete file restoration with metadata tracking (`stash -R`)

### Core Functionality
- **Flexible Usage**: Works with any directories, not just config files
- **Interactive Mode**: Option to interactively specify target directory
- **Recursive Processing**: Can process entire directory trees
- **Advanced Path Handling**: Supports home directory expansion and relative paths
- **Symlink Management**: Creates and manages symlinks while maintaining directory structure
- **Ignore Patterns**: Supports local and global ignore patterns
- **Metadata Tracking**: Each stashed file includes restoration metadata

## Usage

### GNU Stow-like Deployment (Recommended)

```sh
# Deploy all packages from dotfiles repository
cd ~/.dotfiles && stash -d

# Deploy specific package
cd ~/.dotfiles && stash shell

# Using dot syntax (reverse symlinking)
cd ~/.dotfiles/shell && stash .
```

### Traditional Stashing (File Organization)

```sh
# Stash individual files
stash -s ~/.zshrc -t ~/.files

# Stash with interactive target selection
stash -s ~/.config -i

# Recursive stashing
stash -s ~/.config -t ~/.files -r
```

### Restoration

```sh
# Restore stashed files back to original locations
stash -R -s ~/.files/config/app/config.yml
```

### Complete Dotfiles Workflow

```sh
# 1. Stash your configurations
stash -s ~/.zshrc -t ~/.files
stash -s ~/.config/app -t ~/.files

# 2. On a new machine, deploy everything
cd ~/.files && stash -d

# 3. If needed, restore individual files
stash -R -s ~/.files/config/app/config.yml
```

## Common Use Cases

1. **Organizing Dotfiles**:

   ```sh
   # Move config files to dotfiles repo
   guile -L . stash.scm --source ~/.config --target ~/.dotfiles/config --recursive
   ```

2. **Backing Up Documents**:

   ```sh
   # Move documents to external drive
   guile -L . stash.scm --source ~/Documents --target /media/backup/docs --recursive
   ```

3. **Project Organization**:

   ```sh
   # Archive old project while keeping it accessible
   guile -L . stash.scm --source ~/projects/old-app --target ~/archive/projects/old-app
   ```

## Path Handling

Stash handles various path formats:

- Absolute paths: `/home/user/documents`
- Relative paths: `../documents`, `./notes`
- Home directory: `~/documents`
- Dot notation: `.`, `..`

## Ignore Patterns

Stash supports two types of ignore files:

- `.stash-local-ignore`: Directory-specific ignore patterns
- `.stash-global-ignore`: Global ignore patterns

Default ignore patterns:

- `.git` directories
- `.stash-local-ignore` files
- `.DS_Store` files

## Project Structure

```sh
stash/
├── stash.scm              # Main entry point
├── modules/
│   └── stash/
│       ├── paths.scm      # Path handling
│       ├── tree.scm       # Tree operations
│       ├── package.scm    # Package management
│       ├── file-ops.scm   # File operations
│       ├── log.scm        # Logging
│       ├── conflict.scm   # Conflict resolution
│       ├── colors.scm     # Terminal colors
│       └── help.scm       # Help messages
├── README.md             # Project overview
├── USER-GUIDE.md         # Comprehensive user documentation
├── DEVLOG.md            # Development log
└── LICENSE              # GNU GPL v3
```

## Dependencies

- Guile Scheme 3.0.9
- Standard Guile libraries

## Development

See `DEVLOG.md` for detailed development history and recent changes.

## License

`stash` is licensed under the GNU General Public License v3. See the LICENSE file for more information.