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

### Using Guix (Recommended)

1. Add the Stash channel to your `~/.config/guix/channels.scm`:

```scheme
(cons* (channel
        (name 'stash)
        (url "https://codeberg.org/glenneth/stash")
        (branch "main"))
       %default-channels)
```

2. Update your channels and install:

```sh
guix pull
guix install stash
```

3. Configure your shell environment:

```sh
# 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
export PATH=$GUIX_PROFILE/bin:$PATH

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

### 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/
├── .guix-channel/        # Guix channel configuration
│   └── stash/
│       └── packages/
│           └── stash.scm
├── modules/
│   └── stash/
│       ├── colors.scm    # Terminal colors
│       ├── conflict.scm  # Conflict resolution
│       ├── file-ops.scm  # File operations
│       ├── help.scm      # Help messages
│       ├── log.scm       # Logging utilities
│       ├── package.scm   # Package information
│       ├── paths.scm     # Path manipulation
│       └── tree.scm      # Directory tree handling
├── tests/                # Test suite
│   ├── run-tests.sh
│   ├── test-helpers.scm
│   └── *-test.scm       # Individual test files
├── README.md            # Project overview
├── USER_GUIDE.md        # Comprehensive documentation
└── stash.scm           # Main executable
```

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