From 08f06c6b47b817422083aa86667a17e003539e1b Mon Sep 17 00:00:00 2001 From: glenneth1 Date: Fri, 6 Dec 2024 14:33:25 +0300 Subject: [PATCH] docs: merge USER-GUIDE.md and USER_GUIDE.md into single comprehensive guide --- USER-GUIDE.md | 214 ------------------------------------------------ USER_GUIDE.md | 219 +++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 173 insertions(+), 260 deletions(-) delete mode 100644 USER-GUIDE.md diff --git a/USER-GUIDE.md b/USER-GUIDE.md deleted file mode 100644 index 5e7bd11..0000000 --- a/USER-GUIDE.md +++ /dev/null @@ -1,214 +0,0 @@ -# Stash User Guide - -## Table of Contents - -1. [Introduction](#introduction) -2. [Installation](#installation) -3. [Basic Concepts](#basic-concepts) -4. [Usage Patterns](#usage-patterns) -5. [Common Use Cases](#common-use-cases) -6. [Advanced Features](#advanced-features) -7. [Troubleshooting](#troubleshooting) -8. [Tips and Best Practices](#tips-and-best-practices) - -## Introduction - -Stash is a powerful symlink management utility that helps you organize your files by moving them to a target location while maintaining easy access through symbolic links. While it's excellent for managing dotfiles, Stash can organize any type of files or directories. - -### Why Use Stash? - -- **Keep Your Files Organized**: Move files to logical storage locations while maintaining easy access -- **Backup with Access**: Store files in backup locations without changing your workflow -- **Dotfile Management**: Perfect for managing configuration files across different machines -- **Project Organization**: Archive old projects while keeping them accessible -- **Cross-device File Management**: Safely manage files across different storage devices - -## 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 - ``` - -## Basic Concepts - -### How Stash Works - -1. **Source Directory**: The original location of your files -2. **Target Directory**: Where you want to store the files -3. **Symbolic Links**: Created in the source location, pointing to the target - -### Key Terms - -- **Stashing**: The process of moving files to a target location and creating symlinks -- **Dot Syntax**: A shorthand way to create symlinks for previously stashed files -- **Recursive Mode**: Processing entire directory trees - -## Usage Patterns - -### 1. Interactive Mode - -Best for beginners or when you want to choose the target location interactively. - -```sh -stash --source ~/Pictures --interactive -``` - -### 2. Explicit Paths - -When you know exactly where you want to store files. - -```sh -stash --source ~/Documents/notes --target ~/backup/notes -``` - -### 3. Dot Syntax - -Quick way to create symlinks for previously stashed files. - -```sh -cd ~/.dotfiles/config/nvim -stash . # Creates symlink in ~/.config/nvim -``` - -### 4. Recursive Mode - -For processing entire directory trees. - -```sh -stash --source ~/.config --target ~/.dotfiles/config --recursive -``` - -## Common Use Cases - -### 1. Managing Dotfiles - -Keep configuration files in a git repository: - -```sh -# Initial stash -stash --source ~/.config/nvim --target ~/.dotfiles/config/nvim - -# Later, on another machine -cd ~/.dotfiles/config/nvim -stash . -``` - -### 2. Project Organization - -Archive old projects while keeping them accessible: - -```sh -stash --source ~/projects/old-webapp --target ~/archive/projects/webapp -``` - -### 3. Cross-device File Management - -Store large files on external drives: - -```sh -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 - -## Troubleshooting - -### Common Issues and Solutions - -1. **"Permission denied" errors** - - Check file permissions in both source and target locations - - Ensure you have write access to both directories - -2. **"File exists" errors** - - Remove existing symlinks or files before stashing - - Move existing files manually if needed - -3. **Cross-device issues** - - Use the recursive flag for cross-device operations - - Ensure target location has sufficient space - -## Tips and Best Practices - -1. **Organization** - - Keep related files together in the target location - - Use meaningful directory names - - Document your stash organization - -2. **Backup** - - Always back up important files before stashing - - Test symlinks after creation - - Use version control for dotfiles - -3. **Maintenance** - - Regularly check for broken symlinks - - Keep your stash locations organized - - Document your stash structure - -## Command Reference - -### Basic Commands - -```sh -stash --help # Display help -stash --version # Show version -stash --source DIR # Specify source directory -stash --target DIR # Specify target directory -stash --recursive # Process directories recursively -stash --interactive # Interactive target selection -``` - -### Common Command Combinations - -```sh -# Interactive stashing -stash -s ~/Documents -i - -# Recursive stashing with explicit paths -stash -s ~/.config -t ~/.dotfiles/config -r - -# Quick symlink creation -cd ~/.dotfiles/config && stash . -``` diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 2e11271..7316480 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -2,20 +2,41 @@ ## Table of Contents -1. [Installation](#installation) +1. [Introduction](#introduction) +2. [Installation](#installation) - [Using Guix](#using-guix) - [Manual Installation](#manual-installation) -2. [Shell Configuration](#shell-configuration) +3. [Shell Configuration](#shell-configuration) - [Fish Shell](#fish-shell) - [Bash Shell](#bash-shell) - [Zsh Shell](#zsh-shell) -3. [Basic Usage](#basic-usage) -4. [Advanced Features](#advanced-features) -5. [Configuration](#configuration) -6. [Troubleshooting](#troubleshooting) +4. [Basic Concepts](#basic-concepts) +5. [Usage Patterns](#usage-patterns) +6. [Common Use Cases](#common-use-cases) +7. [Advanced Features](#advanced-features) +8. [Configuration](#configuration) +9. [Troubleshooting](#troubleshooting) +10. [Tips and Best Practices](#tips-and-best-practices) + +## Introduction + +Stash is a powerful symlink management utility that helps you organize your files by moving them to a target location while maintaining easy access through symbolic links. While it's excellent for managing dotfiles, Stash can organize any type of files or directories. + +### Why Use Stash? + +- **Keep Your Files Organized**: Move files to logical storage locations while maintaining easy access +- **Backup with Access**: Store files in backup locations without changing your workflow +- **Dotfile Management**: Perfect for managing configuration files across different machines +- **Project Organization**: Archive old projects while keeping them accessible +- **Cross-device File Management**: Safely manage files across different storage devices ## Installation +### Prerequisites + +- Guile Scheme 3.0.9 or later +- Unix-like environment (Linux/macOS) + ### Using Guix The recommended way to install Stash is using the Guix package manager: @@ -47,7 +68,7 @@ If you're not using Guix, you can install Stash manually: 2. Clone and set up the repository: ```sh - git clone https://github.com/yourusername/stash.git + git clone https://codeberg.org/glenneth/stash.git cd stash mkdir -p ~/.guile.d/site/3.0 ln -s $(pwd)/modules/stash ~/.guile.d/site/3.0/ @@ -103,66 +124,134 @@ if [ -f "$GUIX_PROFILE/etc/profile" ]; then fi ``` -## Basic Usage +## Basic Concepts -1. Simple file stashing: +### How Stash Works - ```sh - # Move a directory to backup location - stash -s ~/Documents/notes -t ~/backup/notes - ``` +1. **Source Directory**: The original location of your files +2. **Target Directory**: Where you want to store the files +3. **Symbolic Links**: Created in the source location, pointing to the target -2. Recursive stashing: +### Key Terms - ```sh - # Move entire config directory - stash -s ~/.config -t ~/.dotfiles/config -r - ``` +- **Stashing**: The process of moving files to a target location and creating symlinks +- **Dot Syntax**: A shorthand way to create symlinks for previously stashed files +- **Recursive Mode**: Processing entire directory trees -3. Interactive mode: +## Usage Patterns - ```sh - # Let stash prompt for target location - stash -s ~/Pictures -i - ``` +### 1. Interactive Mode + +Best for beginners or when you want to choose the target location interactively. + +```sh +stash --source ~/Pictures --interactive +``` + +### 2. Explicit Paths + +When you know exactly where you want to store files. + +```sh +stash --source ~/Documents/notes --target ~/backup/notes +``` + +### 3. Dot Syntax + +Quick way to create symlinks for previously stashed files. + +```sh +cd ~/.dotfiles/config/nvim +stash . # Creates symlink in ~/.config/nvim +``` + +### 4. Recursive Mode + +For processing entire directory trees. + +```sh +stash --source ~/.config --target ~/.dotfiles/config --recursive +``` + +## Common Use Cases + +### 1. Managing Dotfiles + +Keep configuration files in a git repository: + +```sh +# Initial stash +stash --source ~/.config/nvim --target ~/.dotfiles/config/nvim + +# Later, on another machine +cd ~/.dotfiles/config/nvim +stash . +``` + +### 2. Project Organization + +Archive old projects while keeping them accessible: + +```sh +stash --source ~/projects/old-webapp --target ~/archive/projects/webapp +``` + +### 3. Cross-device File Management + +Store large files on external drives: + +```sh +stash --source ~/Videos --target /media/external/videos --recursive +``` ## Advanced Features -1. **Ignore Patterns** +### 1. Path Handling - - Create `.stashignore` in source directory - - Add patterns similar to `.gitignore` +- Supports home directory expansion (~) +- Handles both absolute and relative paths +- Maintains directory structure in target location - ```sh - *.tmp - .DS_Store - node_modules/ - ``` +### 2. Symlink Management -2. **Recursive Mode** +- Creates intermediate directories as needed +- Handles existing symlinks gracefully +- Preserves original file permissions - - Use `-r` flag for entire directory trees - - Preserves directory structure - - Creates symlinks for all subdirectories +### 3. Ignore Patterns -3. **Conflict Resolution** - - Automatically detects existing files/symlinks - - Interactive prompts for resolution - - Options to skip, replace, or backup +- Create `.stashignore` in source directory +- Add patterns similar to `.gitignore` + +```sh +*.tmp +.DS_Store +node_modules/ +``` + +### 4. Conflict Resolution + +- Automatically detects existing files/symlinks +- Interactive prompts for resolution +- Options to skip, replace, or backup ## Configuration -1. **Environment Variables** - - `GUILE_AUTO_COMPILE=0`: Disable auto-compilation - - `GUILE_LOAD_PATH`: Add custom module paths - - `GUIX_PROFILE`: Set Guix profile location +### Environment Variables -2. **Global Configuration** - - System-wide ignore patterns in `/etc/stash/ignore` - - User-specific patterns in `~/.config/stash/ignore` +- `GUILE_AUTO_COMPILE=0`: Disable auto-compilation +- `GUILE_LOAD_PATH`: Add custom module paths +- `GUIX_PROFILE`: Set Guix profile location + +### Global Configuration + +- System-wide ignore patterns in `/etc/stash/ignore` +- User-specific patterns in `~/.config/stash/ignore` ## Troubleshooting +### Common Issues and Solutions + 1. **Command Not Found** - Verify Guix profile is sourced correctly - Check PATH includes `~/.guix-profile/bin` @@ -182,5 +271,43 @@ fi - "canonicalize-path override": Normal, can be ignored - "auto-compilation enabled": Set GUILE_AUTO_COMPILE=0 +### Cross-device Issues + +- Use the recursive flag for cross-device operations +- Ensure target location has sufficient space + +## Tips and Best Practices + +1. **Organization** + + - Keep related files together in the target location + - Use meaningful directory names + - Document your stash organization + +2. **Backup** + + - Always back up important files before stashing + - Test symlinks after creation + - Use version control for dotfiles + +3. **Maintenance** + + - Regularly check for broken symlinks + - Keep your stash locations organized + - Document your stash structure + +## Command Reference + +### Basic Commands + +```sh +stash --help # Display help +stash --version # Show version +stash --source DIR # Specify source directory +stash --target DIR # Specify target directory +stash --recursive # Process directories recursively +stash --interactive # Interactive target selection +``` + For more information or to report issues, visit: