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
|
||||
|
||||
## 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue