mirror of https://codeberg.org/glenneth/stash.git
docs: improve USER-GUIDE.md formatting
Add consistent spacing between sections and subsections to improve readability
This commit is contained in:
parent
2b3a131bec
commit
747342588c
|
|
@ -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
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue