stash/README.md

Stash

stash is a command-line utility written in Guile Scheme that helps manage symbolic links (symlinks) for files and directories. This tool is inspired by GNU Stow but written in Guile Scheme. It provides advanced path handling and conflict resolution, allowing users to manage their dotfiles and configuration files effectively.

Key Features

• Advanced Path Handling: Robust support for dot syntax, home directory expansion, and both absolute and relative paths
• Flexible Usage: Supports both dot syntax (.) and explicit source/target paths
• Symlink Management: Creates and manages symlinks while maintaining correct directory structure
• Conflict Resolution: Handles existing files and symlinks gracefully
• Comprehensive Logging: Detailed logging of all operations for tracking and debugging

Usage

There are two ways to use stash:

1. Using explicit source and target directories:

   guile -L . stash.scm --target=<target-dir> --source=<package-dir>
   

2. Using the dot syntax (similar to GNU Stow):

   cd ~/.dotfiles/.config/package
   guile -L . stash.scm .
   

When using the dot syntax (.), stash will:

1. Use the current directory as the package directory
2. Use the parent directory as the stow directory
3. Create symlinks in the corresponding location under your home directory

Examples

1. Explicit paths:

   # Move ~/.config/rofi to ~/.dotfiles/.config and create symlink
   guile -L . stash.scm --target=~/.dotfiles/.config --source=~/.config/rofi
   

2. Dot syntax:

   # Move to your package directory
   cd ~/.dotfiles/.config/rofi
   # Create symlink at ~/.config/rofi
   guile -L . stash.scm .
   

Path Handling

Stash handles various path formats:

• Absolute paths: /home/user/.config
• Relative paths: ../config, ./config
• Home directory: ~/.config
• Dot notation: ., ..

Ignore Patterns

Stash supports two types of ignore files:

• .stash-local-ignore: Package-specific ignore patterns
• .stash-global-ignore: Global ignore patterns for all packages

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.