mirror of https://codeberg.org/glenneth/stash.git
Updated the README.md file
This commit is contained in:
GLENN THOMPSON
parent
9d86d0d7d5
commit
9bf54a5e47
156
README.md
156
README.md
|
|
@ -1,122 +1,74 @@
|
|||
# Guile-Stash
|
||||
|
||||
Guile-Stash is a command-line utility written in Guile Scheme for creating symbolic links (symlinks) for files and directories. It allows users to easily manage links by specifying a source file or directory (`package-dir`) and a target directory (`target-dir`) where the symlink(s) should be created. Guile-Stash supports handling conflicts with existing files or symlinks and provides users with options to overwrite or skip the creation of new symlinks.
|
||||
# Stash
|
||||
|
||||
## Features
|
||||
`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 conflict resolution and an interactive interface, allowing users to move directories to a target location and create symlinks in the source directory's parent folder.
|
||||
|
||||
- **Symlink Creation**: Create symlinks for files and directories from a specified source to a target location.
|
||||
- **Recursive Processing**: For directories, recursively create symlinks for all contained files and subdirectories, preserving the directory structure.
|
||||
- **Command-line Interface**: Easy specification of source and target paths via command-line arguments.
|
||||
- **Conflict Detection and Resolution**: Detects conflicts when a target path for a symlink already exists and prompts the user to overwrite or skip, enhancing control over file organization.
|
||||
- **Color Output**: Incorporates color-coded terminal output to distinguish between different types of messages, improving clarity and user experience.
|
||||
- **Green** for success messages,
|
||||
- **Yellow** for warnings and prompts,
|
||||
- **Red** for errors.
|
||||
- **Graceful Exit**: The program exits more gracefully upon encountering issues, providing clear, colored messages about the nature of the error.
|
||||
## Key Features
|
||||
|
||||
## Current Limitation
|
||||
|
||||
While Guile-Stash effectively handles conflicts with existing directory links, allowing users to choose between overwriting or skipping the creation of a new symlink, it currently does not replace an existing file link directly. This issue stems from the nuanced behavior of symlink creation and deletion within different filesystems and their handling of file vs. directory links.
|
||||
|
||||
The program identifies the existence of a conflict (i.e., when the target path for the new symlink already exists) and correctly prompts the user for action if the conflict involves a linked directory. However, due to current implementation constraints, when the target is an existing file link, the program will gracefully exit with an error message, avoiding potential data loss or unexpected behavior. This ensures that users are made aware of the issue without automatically proceeding with actions that could affect their filesystem unexpectedly.
|
||||
|
||||
## Requirements
|
||||
|
||||
- [Guile Scheme](https://www.gnu.org/software/guile/) (Tested on version 2.2, but newer versions should also work)
|
||||
|
||||
## Installation
|
||||
|
||||
Guile-Stash does not require a traditional installation. However, you will need to have Guile Scheme installed on your system. Follow the [official Guile installation guide](https://www.gnu.org/software/guile/download/) for instructions.
|
||||
|
||||
Once Guile is installed, download `guile-stash.scm` to your preferred directory.
|
||||
- **Move and Symlink**: `stash` moves entire directories to a specified target directory and creates a symlink in the original parent directory.
|
||||
- **Conflict Handling**: When a conflict occurs (e.g., an existing symlink), the user is prompted to either overwrite, skip, or cancel.
|
||||
- **Logging**: All actions, such as moving directories, creating symlinks, and resolving conflicts, are logged in `guile-stash.log`.
|
||||
- **Command-Line Interface**: Command-line parsing allows for specifying the source and target directories.
|
||||
|
||||
## Usage
|
||||
|
||||
To use Guile-Stash, navigate to the directory containing `guile-stash.scm` and run the following command in your terminal:
|
||||
|
||||
```bash
|
||||
guile -L . guile-stash.scm --target=<target-dir> --package-dir=<package-dir>
|
||||
```sh
|
||||
guile -L . stash.scm --target=<target-dir> --source=<package-dir>
|
||||
```
|
||||
Replace <target-dir> with the path to the directory where you want the symlink(s) to be created, and <package-dir> with the path to the source file or directory.
|
||||
Options
|
||||
|
||||
--target: Specifies the target directory where symlinks will be created.
|
||||
--package-dir: Specifies the path to the source file or directory for which symlinks will be created.
|
||||
- `<target-dir>`: Directory where the package directory will be moved.
|
||||
- `<source>`: Directory to be moved and symlinked.
|
||||
|
||||
### Conflict Resolution
|
||||
## Example
|
||||
|
||||
If a conflict is detected (e.g., a file or symlink already exists at the target location), Guile-Stash will prompt you for action:
|
||||
Suppose you want to move `~/.config/rofi` to `~/.dotfiles/.config` and create a symlink at `~/.config/rofi` pointing to the new location. You would run:
|
||||
|
||||
o: Overwrite the existing file or symlink with the new symlink.
|
||||
s: Skip creating the new symlink and leave the existing file or symlink untouched.
|
||||
|
||||
Examples
|
||||
|
||||
Creating a symlink for a single file:
|
||||
```bash
|
||||
guile -L . guile-stash.scm --target=/path/to/target --package-dir=/path/to/source/file.txt
|
||||
```sh
|
||||
guile -L . stash.scm --target=~/.dotfiles/.config --source=~/.config/rofi
|
||||
```
|
||||
Creating symlinks for all files in a directory:
|
||||
```bash
|
||||
guile -L . guile-stash.scm --target=/path/to/target --package-dir=/path/to/source/directory
|
||||
```
|
||||
## Contributing
|
||||
|
||||
Thank you for considering contributing to this project! Here's how you can get involved:
|
||||
This moves the `rofi` directory to `~/.dotfiles/.config` and creates a symlink in `~/.config` pointing to the new location.
|
||||
|
||||
### Pull Requests
|
||||
## Conflict Resolution
|
||||
|
||||
1. **Fork the repository on Codeberg**: You can find the "Fork" button on the top-right of the project page.
|
||||
2. **Clone your fork** to your local machine:
|
||||
```bash
|
||||
git clone https://codeberg.org/your-username/your-repo.git
|
||||
cd your-repo
|
||||
```
|
||||
3. **Create a new branch** for your changes:
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
```
|
||||
4. **Make your changes** and **commit them** with a clear message:
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Description of your changes"
|
||||
```
|
||||
5. **Push the changes** to your fork:
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
6. **Open a pull request** from your branch on Codeberg.
|
||||
If a symlink already exists at the target location, `guile-stash` detects this and prompts the user to either:
|
||||
|
||||
Contributions to Guile-Stash are welcome. Please feel free to fork the repository, make your changes, and submit a patch or topic for discussion.
|
||||
Your pull request will be reviewed, and feedback might be provided if necessary. Once approved, it will be merged into the main project.
|
||||
- **Overwrite**: Remove the existing symlink and create a new one.
|
||||
- **Skip**: Keep the existing symlink and skip creating a new one.
|
||||
- **Cancel**: Cancel the operation.
|
||||
|
||||
## Logging
|
||||
|
||||
All actions taken by the program are logged in a file named `stash.log`. This includes:
|
||||
|
||||
- Moving directories.
|
||||
- Creating symlinks.
|
||||
- Conflict resolutions.
|
||||
|
||||
Example log entry:
|
||||
```
|
||||
Moved /home/glenn/.config/rofi to /home/glenn/.dotfiles/.config/rofi
|
||||
Symlink created at /home/glenn/.config/rofi pointing to /home/glenn/.dotfiles/.config/rofi
|
||||
```
|
||||
|
||||
## Improvements
|
||||
|
||||
Here’s a summary of the recent improvements:
|
||||
|
||||
1. **Move Entire Directory**: Instead of copying, the program now moves the entire directory from the package directory to the target directory.
|
||||
|
||||
2. **Path Expansion**: The program now correctly expands `~` to the full path using `$HOME`, ensuring compatibility with home directory shortcuts.
|
||||
|
||||
3. **Logging Functionality**: All operations are logged to `stash.log` to track actions like moving directories and creating symlinks.
|
||||
|
||||
4. **Modular Functions**: The program is now structured with modular functions for path expansion, conflict handling, and symlink creation.
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- Add support for a non-interactive mode for automation workflows.
|
||||
- Improve error handling for more specific error types and exit codes.
|
||||
- Extend conflict resolution options with more advanced features (e.g., backup, replace).
|
||||
|
||||
## License
|
||||
|
||||
Guile-Stash is licensed under the MIT License. For more details, see the [LICENSE](https://codeberg.org/glenneth/stash/src/branch/dev/LICENSE) file for details.
|
||||
|
||||
This README provides a starting point. Feel free to expand it with more detailed examples, configuration options, or a more comprehensive guide on contributing to the project.
|
||||
|
||||
## Credits and Acknowledgements
|
||||
|
||||
Guile-Stash wouldn't be what it is today without the support and contributions from the community. A huge thank you goes out to:
|
||||
|
||||
- **The Guile Scheme Community**: For providing an excellent programming environment and being an invaluable resource for learning and troubleshooting.
|
||||
- **Open Source Contributors**: Special thanks to everyone who has contributed to making Guile-Stash better, whether through code, documentation, or helping with issues.
|
||||
- **David Wilson**: For the guidance, inspiration, and support throughout the development of this project.
|
||||
- **Tooling and Libraries**: A shout-out to the developers of `(ice-9 getopt-long)`, `(ice-9 popen)`, `(ice-9 rdelim)`, and other Guile modules that made this project possible.
|
||||
- **You**: Yes, you reading this! Whether you're using Guile-Stash, providing feedback, or simply showing interest, you're a vital part of this project's journey.
|
||||
|
||||
## Special Thanks
|
||||
|
||||
This project, **Guile-Stash**, wouldn't be what it is without the invaluable resources, discussions, and community support from various individuals and platforms. A special thank you goes to:
|
||||
|
||||
- **[System Crafters](https://systemcrafters.net/)**: For their incredible content on Emacs, programming, and much more. Their tutorials and discussions have been a source of inspiration and learning.
|
||||
|
||||
- **#systemcrafters IRC Channel**: A vibrant community of knowledgeable and friendly folks on Libera.Chat. Their insights and advice have been instrumental in the development of this tool. You can join the #systemcrafters channel on [Libera.Chat](https://libera.chat/) IRC to connect with the community.
|
||||
|
||||
- **[System Crafters Forum](https://forum.systemcrafters.net/)**: For providing a welcoming platform for in-depth discussions, questions, and sharing knowledge about various programming and customization topics.
|
||||
|
||||
A huge thank you to everyone who contributed, offered feedback, or shared their knowledge and experiences. Your support and encouragement have been crucial to this project's development.
|
||||
|
||||
|
||||
If you feel like your name belongs in this list, don't hesitate to reach out or contribute to the project!
|
||||
`stash` is licensed under the MIT License. See the LICENSE file for details.
|
||||
|
|
|
|||
|
|
@ -51,6 +51,8 @@
|
|||
|
||||
;; #TODO Addition of a Non-Interactive Mode: Adding a non-interactive mode that automatically skips or overwrites conflicts (based on a command-line flag) could make the script more flexible for use in automation workflows. e.g.
|
||||
|
||||
;;; CODE
|
||||
|
||||
;; Import necessary modules
|
||||
(use-modules (ice-9 getopt-long)
|
||||
(ice-9 popen)
|
||||
|
|
|
|||
Loading…
Reference in New Issue