docs: improve USER-GUIDE.md formatting

Add consistent spacing between sections and subsections
to improve readability
This commit is contained in:
glenneth1 2024-12-06 09:09:32 +03:00
parent 2b3a131bec
commit 747342588c
1 changed files with 18 additions and 0 deletions

View File

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