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.

Features

• 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.

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 (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 for instructions.

Once Guile is installed, download guile-stash.scm to your preferred directory.

Usage

To use Guile-Stash, navigate to the directory containing guile-stash.scm and run the following command in your terminal:

guile -L . guile-stash.scm --target=<target-dir> --package-dir=<package-dir>

Replace with the path to the directory where you want the symlink(s) to be created, and 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.

Conflict Resolution

If a conflict is detected (e.g., a file or symlink already exists at the target location), Guile-Stash will prompt you for action:

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:

guile -L . guile-stash.scm --target=/path/to/target --package-dir=/path/to/source/file.txt

Creating symlinks for all files in a directory:

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:

Pull Requests

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:

   git clone https://codeberg.org/your-username/your-repo.git
   cd your-repo

3. Create a new branch for your changes:

git checkout -b feature/your-feature-name

4. Make your changes and commit them with a clear message:

git add .
git commit -m "Description of your changes"

5. Push the changes to your fork:

git push origin feature/your-feature-name

6. Open a pull request from your branch on Codeberg.

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.

License

Guile-Stash is licensed under the MIT License. For more details, see the 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: 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 IRC to connect with the community.

• System Crafters Forum: 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!