glenn
/
stash
mirror of https://codeberg.org/glenneth/stash.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: merge USER-GUIDE.md and USER_GUIDE.md into single comprehensive guide

This commit is contained in:
glenneth1 2024-12-06 14:33:25 +03:00
parent e089493983
commit 08f06c6b47
2 changed files with 173 additions and 260 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
USER-GUIDE.md
View File

@ -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 .
```

219
USER_GUIDE.md
View File

@ -2,20 +2,41 @@
## Table of Contents ## Table of Contents
1. [Installation](#installation) 1. [Introduction](#introduction)
2. [Installation](#installation)
- [Using Guix](#using-guix) - [Using Guix](#using-guix)
- [Manual Installation](#manual-installation) - [Manual Installation](#manual-installation)
2. [Shell Configuration](#shell-configuration) 3. [Shell Configuration](#shell-configuration)
- [Fish Shell](#fish-shell) - [Fish Shell](#fish-shell)
- [Bash Shell](#bash-shell) - [Bash Shell](#bash-shell)
- [Zsh Shell](#zsh-shell) - [Zsh Shell](#zsh-shell)
3. [Basic Usage](#basic-usage) 4. [Basic Concepts](#basic-concepts)
4. [Advanced Features](#advanced-features) 5. [Usage Patterns](#usage-patterns)
5. [Configuration](#configuration) 6. [Common Use Cases](#common-use-cases)
6. [Troubleshooting](#troubleshooting) 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 ## Installation
### Prerequisites
- Guile Scheme 3.0.9 or later
- Unix-like environment (Linux/macOS)
### Using Guix ### Using Guix
The recommended way to install Stash is using the Guix package manager: 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: 2. Clone and set up the repository:
```sh ```sh
git clone https://github.com/yourusername/stash.git git clone https://codeberg.org/glenneth/stash.git
cd stash cd stash
mkdir -p ~/.guile.d/site/3.0 mkdir -p ~/.guile.d/site/3.0
ln -s $(pwd)/modules/stash ~/.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 fi
``` ```
## Basic Usage ## Basic Concepts
1. Simple file stashing: ### How Stash Works
```sh 1. **Source Directory**: The original location of your files
# Move a directory to backup location 2. **Target Directory**: Where you want to store the files
stash -s ~/Documents/notes -t ~/backup/notes 3. **Symbolic Links**: Created in the source location, pointing to the target
```
2. Recursive stashing: ### Key Terms
```sh - **Stashing**: The process of moving files to a target location and creating symlinks
# Move entire config directory - **Dot Syntax**: A shorthand way to create symlinks for previously stashed files
stash -s ~/.config -t ~/.dotfiles/config -r - **Recursive Mode**: Processing entire directory trees
```
3. Interactive mode: ## Usage Patterns
```sh ### 1. Interactive Mode
# Let stash prompt for target location
stash -s ~/Pictures -i 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 ## Advanced Features
1. **Ignore Patterns** ### 1. Path Handling
- Create `.stashignore` in source directory - Supports home directory expansion (~)
- Add patterns similar to `.gitignore` - Handles both absolute and relative paths
- Maintains directory structure in target location
```sh ### 2. Symlink Management
*.tmp
.DS_Store
node_modules/
```
2. **Recursive Mode** - Creates intermediate directories as needed
- Handles existing symlinks gracefully
- Preserves original file permissions
- Use `-r` flag for entire directory trees ### 3. Ignore Patterns
- Preserves directory structure
- Creates symlinks for all subdirectories
3. **Conflict Resolution** - Create `.stashignore` in source directory
- Automatically detects existing files/symlinks - Add patterns similar to `.gitignore`
- Interactive prompts for resolution
- Options to skip, replace, or backup ```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 ## Configuration
1. **Environment Variables** ### Environment Variables
- `GUILE_AUTO_COMPILE=0`: Disable auto-compilation
- `GUILE_LOAD_PATH`: Add custom module paths
- `GUIX_PROFILE`: Set Guix profile location
2. **Global Configuration** - `GUILE_AUTO_COMPILE=0`: Disable auto-compilation
- System-wide ignore patterns in `/etc/stash/ignore` - `GUILE_LOAD_PATH`: Add custom module paths
- User-specific patterns in `~/.config/stash/ignore` - `GUIX_PROFILE`: Set Guix profile location
### Global Configuration
- System-wide ignore patterns in `/etc/stash/ignore`
- User-specific patterns in `~/.config/stash/ignore`
## Troubleshooting ## Troubleshooting
### Common Issues and Solutions
1. **Command Not Found** 1. **Command Not Found**
- Verify Guix profile is sourced correctly - Verify Guix profile is sourced correctly
- Check PATH includes `~/.guix-profile/bin` - Check PATH includes `~/.guix-profile/bin`
@ -182,5 +271,43 @@ fi
- "canonicalize-path override": Normal, can be ignored - "canonicalize-path override": Normal, can be ignored
- "auto-compilation enabled": Set GUILE_AUTO_COMPILE=0 - "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: For more information or to report issues, visit:
<https://codeberg.org/glenneth/stash> <https://codeberg.org/glenneth/stash>