mirror of https://codeberg.org/glenneth/stash.git
174 lines
4.1 KiB
Markdown
174 lines
4.1 KiB
Markdown
# Stash User Guide
|
|
|
|
## Table of Contents
|
|
1. [Installation](#installation)
|
|
- [Using Guix](#using-guix)
|
|
- [Manual Installation](#manual-installation)
|
|
2. [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)
|
|
|
|
## Installation
|
|
|
|
### Using Guix
|
|
|
|
The recommended way to install Stash is using the Guix package manager:
|
|
|
|
```sh
|
|
# Install from local package definition
|
|
guix package --install-from-file=minimal-package.scm
|
|
```
|
|
|
|
After installation, the `stash` executable will be available in your Guix profile at `~/.guix-profile/bin/stash`.
|
|
|
|
### Manual Installation
|
|
|
|
If you're not using Guix, you can install Stash manually:
|
|
|
|
1. Install prerequisites:
|
|
```sh
|
|
# Debian/Ubuntu
|
|
sudo apt-get install guile-3.0
|
|
|
|
# Fedora
|
|
sudo dnf install guile30
|
|
|
|
# Arch Linux
|
|
sudo pacman -S guile
|
|
```
|
|
|
|
2. Clone and set up the repository:
|
|
```sh
|
|
git clone https://github.com/yourusername/stash.git
|
|
cd stash
|
|
mkdir -p ~/.guile.d/site/3.0
|
|
ln -s $(pwd)/modules/stash ~/.guile.d/site/3.0/
|
|
```
|
|
|
|
## Shell Configuration
|
|
|
|
### Fish Shell
|
|
|
|
1. Add to `~/.config/fish/config.fish`:
|
|
```fish
|
|
# Guix environment setup
|
|
set -gx GUIX_PROFILE $HOME/.guix-profile
|
|
set -gx PATH $GUIX_PROFILE/bin $PATH
|
|
|
|
# Load Guix environment variables
|
|
if test -f $GUIX_PROFILE/etc/profile
|
|
for line in (cat $GUIX_PROFILE/etc/profile | grep '^export' | string replace 'export ' '')
|
|
set var (string split '=' $line)
|
|
set -gx $var[1] (eval echo $var[2])
|
|
end
|
|
end
|
|
```
|
|
|
|
2. Alternative method using symlink:
|
|
```fish
|
|
ln -sf ~/.guix-profile/bin/stash ~/.local/bin/stash
|
|
```
|
|
|
|
### Bash Shell
|
|
|
|
Add to `~/.bashrc`:
|
|
```bash
|
|
# Guix environment setup
|
|
export GUIX_PROFILE="$HOME/.guix-profile"
|
|
if [ -f "$GUIX_PROFILE/etc/profile" ]; then
|
|
. "$GUIX_PROFILE/etc/profile"
|
|
fi
|
|
```
|
|
|
|
### Zsh Shell
|
|
|
|
Add to `~/.zshrc`:
|
|
```zsh
|
|
# Guix environment setup
|
|
export GUIX_PROFILE="$HOME/.guix-profile"
|
|
if [ -f "$GUIX_PROFILE/etc/profile" ]; then
|
|
. "$GUIX_PROFILE/etc/profile"
|
|
fi
|
|
```
|
|
|
|
## Basic Usage
|
|
|
|
1. Simple file stashing:
|
|
```sh
|
|
# Move a directory to backup location
|
|
stash -s ~/Documents/notes -t ~/backup/notes
|
|
```
|
|
|
|
2. Recursive stashing:
|
|
```sh
|
|
# Move entire config directory
|
|
stash -s ~/.config -t ~/.dotfiles/config -r
|
|
```
|
|
|
|
3. Interactive mode:
|
|
```sh
|
|
# Let stash prompt for target location
|
|
stash -s ~/Pictures -i
|
|
```
|
|
|
|
## Advanced Features
|
|
|
|
1. **Ignore Patterns**
|
|
- Create `.stashignore` in source directory
|
|
- Add patterns similar to `.gitignore`
|
|
```
|
|
*.tmp
|
|
.DS_Store
|
|
node_modules/
|
|
```
|
|
|
|
2. **Recursive Mode**
|
|
- Use `-r` flag for entire directory trees
|
|
- Preserves directory structure
|
|
- Creates symlinks for all subdirectories
|
|
|
|
3. **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
|
|
|
|
2. **Global Configuration**
|
|
- System-wide ignore patterns in `/etc/stash/ignore`
|
|
- User-specific patterns in `~/.config/stash/ignore`
|
|
|
|
## Troubleshooting
|
|
|
|
1. **Command Not Found**
|
|
- Verify Guix profile is sourced correctly
|
|
- Check PATH includes `~/.guix-profile/bin`
|
|
- Try creating symlink in `~/.local/bin`
|
|
|
|
2. **Module Loading Issues**
|
|
- Ensure GUILE_LOAD_PATH includes module directory
|
|
- Check module permissions and ownership
|
|
- Verify Guile version compatibility
|
|
|
|
3. **Permission Errors**
|
|
- Check file/directory permissions
|
|
- Ensure write access to target location
|
|
- Verify symlink creation permissions
|
|
|
|
4. **Common Warnings**
|
|
- "canonicalize-path override": Normal, can be ignored
|
|
- "auto-compilation enabled": Set GUILE_AUTO_COMPILE=0
|
|
|
|
For more information or to report issues, visit:
|
|
https://codeberg.org/glenneth/stash
|