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

1. Prerequisites:

   • Guile Scheme 3.0.9 or later
   • A Unix-like environment (Linux/macOS)

2. Installation Steps:

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

   # Test if stash works
   stash --help
   

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

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

2. Explicit Paths:

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

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

4. Dot Syntax (after files are stashed):

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

Common Use Cases

1. Organizing Dotfiles:

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

2. Backing Up Documents:

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

3. Project Organization:

   # 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

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
├── DEVLOG.md             # Development log
└── LICENSE

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.