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