diff --git a/USER-GUIDE.md b/USER-GUIDE.md index 3db4790..5e7bd11 100644 --- a/USER-GUIDE.md +++ b/USER-GUIDE.md @@ -1,6 +1,7 @@ # Stash User Guide ## Table of Contents + 1. [Introduction](#introduction) 2. [Installation](#installation) 3. [Basic Concepts](#basic-concepts) @@ -25,30 +26,36 @@ Stash is a powerful symlink management utility that helps you organize your file ## Installation ### Prerequisites + - Guile Scheme 3.0.9 or later - Unix-like environment (Linux/macOS) ### Step-by-Step Installation 1. **Clone the Repository**: + ```sh git clone https://codeberg.org/glenneth/stash.git cd stash ``` 2. **Set Up Guile Load Path**: + ```sh mkdir -p ~/.guile.d/site/3.0 ln -s $(pwd)/modules/stash ~/.guile.d/site/3.0/ ``` 3. **Create Convenient Alias** (Optional): + Add to your shell config (~/.bashrc or ~/.zshrc): + ```sh alias stash="guile -L $(pwd) $(pwd)/stash.scm" ``` 4. **Verify Installation**: + ```sh stash --help ``` @@ -70,6 +77,7 @@ Stash is a powerful symlink management utility that helps you organize your file ## Usage Patterns ### 1. Interactive Mode + Best for beginners or when you want to choose the target location interactively. ```sh @@ -77,6 +85,7 @@ stash --source ~/Pictures --interactive ``` ### 2. Explicit Paths + When you know exactly where you want to store files. ```sh @@ -84,6 +93,7 @@ stash --source ~/Documents/notes --target ~/backup/notes ``` ### 3. Dot Syntax + Quick way to create symlinks for previously stashed files. ```sh @@ -92,6 +102,7 @@ stash . # Creates symlink in ~/.config/nvim ``` ### 4. Recursive Mode + For processing entire directory trees. ```sh @@ -101,6 +112,7 @@ stash --source ~/.config --target ~/.dotfiles/config --recursive ## Common Use Cases ### 1. Managing Dotfiles + Keep configuration files in a git repository: ```sh @@ -113,6 +125,7 @@ stash . ``` ### 2. Project Organization + Archive old projects while keeping them accessible: ```sh @@ -120,6 +133,7 @@ stash --source ~/projects/old-webapp --target ~/archive/projects/webapp ``` ### 3. Cross-device File Management + Store large files on external drives: ```sh @@ -129,11 +143,13 @@ stash --source ~/Videos --target /media/external/videos --recursive ## Advanced Features ### 1. Path Handling + - Supports home directory expansion (~) - Handles both absolute and relative paths - Maintains directory structure in target location ### 2. Symlink Management + - Creates intermediate directories as needed - Handles existing symlinks gracefully - Preserves original file permissions @@ -174,6 +190,7 @@ stash --source ~/Videos --target /media/external/videos --recursive ## Command Reference ### Basic Commands + ```sh stash --help # Display help stash --version # Show version @@ -184,6 +201,7 @@ stash --interactive # Interactive target selection ``` ### Common Command Combinations + ```sh # Interactive stashing stash -s ~/Documents -i