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

Path Handling Improvements

• Enhanced canonicalize-path function to handle:
  • Dot (.) and dot-dot (..) notation
  • Home directory expansion (~)
  • Absolute and relative paths
• Improved path resolution for both dot syntax and explicit paths

Symlink Creation

• Rewrote plan-operations function to handle:
  • Dot syntax (stash .)
  • Explicit source/target paths
• Fixed symlink creation to maintain correct directory structure
• Added support for creating parent directories as needed

Package Management

• Implemented package record type for managing:
  • Package name
  • Source path
  • Target path
  • Ignore patterns
• Added support for reading ignore patterns from:
  • .stash-local-ignore
  • .stash-global-ignore

Testing

• Added comprehensive test suite
• Implemented test cases for:
  • Dot syntax stashing
  • Explicit path stashing
  • Path resolution
  • Symlink creation

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

Symlink Creation Process

1. Determines source and target paths
2. Creates parent directories if needed
3. Removes existing symlink/directory if present
4. Creates new symlink pointing to correct location

Path Resolution

• Handles both absolute and relative paths
• Expands home directory references
• Resolves dot and dot-dot notation
• Maintains correct directory structure

Known Issues

• Warning about overriding core binding canonicalize-path
  • This is expected behavior and doesn't affect functionality
  • Could be addressed in future by renaming the function

Future Plans

1. Implement more robust conflict resolution
2. Add comprehensive documentation
3. Optimize path handling
4. Address module import warnings
5. Add user configuration options
6. Enhance cross-platform support

Dependencies

• Guile Scheme 3.0.9
• Standard Guile libraries
• Custom modules for path handling and file operations