stash/README.md

# Stash

`stash` is a command-line utility written in Guile Scheme that helps organize your files by moving them to a target location and creating symbolic links (symlinks) in their original location. While it's great for managing dotfiles, it works with any directories you want to organize.

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

- **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

## Usage

Stash offers several ways to organize your files:

1. **Interactive Mode** (easiest for beginners):

   ```sh
   # Move Pictures directory to a backup location
   guile -L . stash.scm --source ~/Pictures --interactive
   ```

2. **Explicit Paths**:

   ```sh
   # Move Documents to backup while keeping symlink
   guile -L . stash.scm --source ~/Documents/notes --target ~/backup/notes
   
   # Move project to code archive
   guile -L . stash.scm --source ~/projects/webapp --target ~/code/archive/webapp
   ```

3. **Recursive Mode** (for entire directory trees):

   ```sh
   # Archive entire projects directory
   guile -L . stash.scm --source ~/projects --target ~/archive/projects --recursive
   ```

4. **Dot Syntax** (after files are stashed):

   ```sh
   # Recreate symlink for previously stashed directory
   cd ~/backup/notes
   guile -L . stash.scm .
   ```

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