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:

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

2. Update your channels and install:

guix pull
guix install stash

3. Configure your shell environment:

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

   # 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
   

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:

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

   # 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/
├── .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.