stash/DEVLOG.md

Stash Development Log

This document tracks the development progress and major changes in the Stash project.

Project Overview

Stash is a symlink management utility written in Guile Scheme, designed to help users manage their dotfiles and configuration files. It provides functionality similar to GNU Stow but with enhanced features for path handling and conflict resolution.

Architecture

The project is organized into several modules:

• stash.scm: Main entry point and command-line interface
• modules/stash/paths.scm: Path manipulation utilities
• modules/stash/tree.scm: Tree operations for symlink creation
• modules/stash/package.scm: Package management functionality
• modules/stash/file-ops.scm: File system operations
• modules/stash/log.scm: Logging utilities
• modules/stash/conflict.scm: Conflict resolution
• modules/stash/colors.scm: ANSI color support for terminal output
• modules/stash/help.scm: Help and usage information

Recent Changes

Testing Infrastructure

• Implemented comprehensive test suite with srfi-64
• Added test-helpers module for common test operations
• Created test cases for all core modules
• Fixed test runner to use primitive-load for better module handling
• Added proper cleanup of test directories

Path Handling Improvements

• Renamed canonicalize-path to normalize-path for clarity
• Enhanced path normalization to handle:
  • Dot (.) and dot-dot (..) notation
  • Home directory expansion (~)
  • Absolute and relative paths
  • Redundant path separators
• Improved path comparison with proper normalization
• Added robust path resolution for symlinks

Tree Operations Enhancement

• Implemented efficient tree traversal with fold-tree
• Added proper directory scanning with ignore patterns
• Improved symlink planning with cycle detection
• Enhanced tree comparison functionality
• Added support for recursive operations
• Fixed directory structure preservation

Module Organization

• Resolved import conflicts between modules
• Fixed warnings about duplicate bindings
• Improved module interface consistency
• Enhanced error handling and reporting
• Added proper documentation strings

Distribution

• Configured Guix channel for distribution
• Updated package definition
• Added proper version tracking
• Improved installation documentation

Current Operation

Stash now supports three main modes of operation:

1. Dot Syntax:

   cd ~/.dotfiles/.config/package
   stash .
   

   • Uses current directory as package directory
   • Uses parent as stow directory
   • Creates symlink in ~/.config/package

2. Explicit Paths:

   stash --source=~/.config/package --target=~/.dotfiles/.config
   

   • Moves package from source to target
   • Creates symlink at original location

3. Interactive Mode:

   stash --source=~/.config/package --interactive
   

   • Takes source directory as input
   • Interactively prompts for target directory
   • Ideal for first-time users and exploratory stashing

Tree Traversal Process

1. Scans source directory recursively
2. Builds tree representation
3. Applies ignore patterns
4. Plans symlink operations
5. Validates tree structure
6. Creates necessary symlinks

Error Handling

• Detects circular symlinks
• Validates path existence
• Checks permissions
• Handles conflicts gracefully
• Provides detailed error messages

Next Steps

1. API Documentation

   • Document module interfaces
   • Add usage examples
   • Create API reference

2. Feature Enhancements

   • Add backup functionality
   • Enhance conflict resolution
   • Improve error reporting

3. Performance Optimization

   • Profile tree operations
   • Optimize path handling
   • Improve memory usage