mirror of https://codeberg.org/glenneth/stash.git
108 lines
3.0 KiB
Markdown
108 lines
3.0 KiB
Markdown
# Stash
|
|
|
|
`stash` is a command-line utility written in Guile Scheme that helps manage symbolic links (symlinks) for files and directories. This tool is inspired by GNU Stow but written in Guile Scheme. It provides advanced path handling and conflict resolution, allowing users to manage their dotfiles and configuration files effectively.
|
|
|
|
## Key Features
|
|
|
|
- **Advanced Path Handling**: Robust support for dot syntax, home directory expansion, and both absolute and relative paths
|
|
- **Flexible Usage**: Supports both dot syntax (.) and explicit source/target paths
|
|
- **Symlink Management**: Creates and manages symlinks while maintaining correct directory structure
|
|
- **Conflict Resolution**: Handles existing files and symlinks gracefully
|
|
- **Comprehensive Logging**: Detailed logging of all operations for tracking and debugging
|
|
|
|
## Usage
|
|
|
|
There are two ways to use stash:
|
|
|
|
1. Using explicit source and target directories:
|
|
|
|
```sh
|
|
guile -L . stash.scm --target=<target-dir> --source=<package-dir>
|
|
```
|
|
|
|
2. Using the dot syntax (similar to GNU Stow):
|
|
|
|
```sh
|
|
cd ~/.dotfiles/.config/package
|
|
guile -L . stash.scm .
|
|
```
|
|
|
|
When using the dot syntax (`.`), stash will:
|
|
|
|
1. Use the current directory as the package directory
|
|
2. Use the parent directory as the stow directory
|
|
3. Create symlinks in the corresponding location under your home directory
|
|
|
|
### Examples
|
|
|
|
1. Explicit paths:
|
|
|
|
```sh
|
|
# Move ~/.config/rofi to ~/.dotfiles/.config and create symlink
|
|
guile -L . stash.scm --target=~/.dotfiles/.config --source=~/.config/rofi
|
|
```
|
|
|
|
2. Dot syntax:
|
|
|
|
```sh
|
|
# Move to your package directory
|
|
cd ~/.dotfiles/.config/rofi
|
|
# Create symlink at ~/.config/rofi
|
|
guile -L . stash.scm .
|
|
```
|
|
|
|
## Path Handling
|
|
|
|
Stash handles various path formats:
|
|
|
|
- Absolute paths: `/home/user/.config`
|
|
- Relative paths: `../config`, `./config`
|
|
- Home directory: `~/.config`
|
|
- Dot notation: `.`, `..`
|
|
|
|
## Ignore Patterns
|
|
|
|
Stash supports two types of ignore files:
|
|
|
|
- `.stash-local-ignore`: Package-specific ignore patterns
|
|
- `.stash-global-ignore`: Global ignore patterns for all packages
|
|
|
|
Default ignore patterns:
|
|
|
|
- `.git` directories
|
|
- `.stash-local-ignore` files
|
|
- `.DS_Store` files
|
|
|
|
## Project Structure
|
|
|
|
```sh
|
|
stash/
|
|
├── stash.scm # Main entry point
|
|
├── modules/
|
|
│ └── stash/
|
|
│ ├── paths.scm # Path handling
|
|
│ ├── tree.scm # Tree operations
|
|
│ ├── package.scm # Package management
|
|
│ ├── file-ops.scm # File operations
|
|
│ ├── log.scm # Logging
|
|
│ ├── conflict.scm # Conflict resolution
|
|
│ ├── colors.scm # Terminal colors
|
|
│ └── help.scm # Help messages
|
|
├── README.md
|
|
├── DEVLOG.md # Development log
|
|
└── LICENSE
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- Guile Scheme 3.0.9
|
|
- Standard Guile libraries
|
|
|
|
## Development
|
|
|
|
See `DEVLOG.md` for detailed development history and recent changes.
|
|
|
|
## License
|
|
|
|
`stash` is licensed under the GNU General Public License v3. See the LICENSE file for more information.
|