mirror of https://codeberg.org/glenneth/stash.git
docs: merge USER-GUIDE.md and USER_GUIDE.md into single comprehensive guide
This commit is contained in:
glenneth1
parent
e089493983
commit
08f06c6b47
214
USER-GUIDE.md
214
USER-GUIDE.md
|
|
@ -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
219
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:
|
||||
<https://codeberg.org/glenneth/stash>
|
||||
|
|
|
|||
Loading…
Reference in New Issue