Here’s a comprehensive documentation for your Bucket Dependency Manager, designed for easy understanding and practical use.

---

Bucket Dependency Manager Documentation

Author: Astridot

License: Makoschin Free Software License (MFSL)

Bucket is a lightweight, flexible dependency manager designed for managing projects in any language. With features like branching, version control, and pull request management, it supports collaborative development and simplifies dependency handling.

---

Features

• Dependency Management: Add, edit, list, install, and remove dependencies.
• Branching: Create, switch, list, and delete branches for isolated development workflows.
• Versioning: Save, list, and rollback to specific project states with version snapshots.
• Pull Requests: Create, list, view, and approve pull requests between branches.
• Entrypoint Commands: Set and run entrypoint commands for your project.

---

Installation

Ensure you have Python 3.12 or later installed.

Using pip:

pip install bkt

CLI Commands

The CLI commands are invoked using bucket or bucket<version> (e.g. bucket6) after installation.

---

Getting Started

1. Initialize a Bucket

To start using Bucket in a project:

bucket init

This creates a .bucket directory and sets up the necessary structure.

---

2. Manage Dependencies

• Add a dependency by specifying its name, source, and optional version or install command:

bucket dep add --name <name> --source <source> --version <version> --install-command <command>

• List all dependencies:

  bucket dep list

• Remove a dependency:

  bucket dep rm <name>

• Install dependencies:

  bucket dep install <name>

Example:

bucket dep add --name requests --source https://pypi.org/project/requests --version 2.31 --install-command "pip install requests==2.31"

---

3. Manage Branches

Branches allow isolated development for specific dependencies.

• Create a branch:

  bucket branch create --name <branch-name>

• Switch to a branch:

  bucket branch switch --name <branch-name>

• List branches:

  bucket branch list

• Delete a branch:

  bucket branch rm --name <branch-name>

---

4. Handle Pull Requests

Collaborate by merging changes using pull requests.

• Create a pull request:

  bucket pr create --source <source-branch> --target <target-branch> --description "<description>"

• Approve and merge a pull request:

  bucket pr approve --id1 <pr-id> --id2 <pr-id2>

• List open pull requests:

  bucket pr list

• View a pull request:

  bucket pr info --id1 <pr-id> --id2 <pr-id2>

---

5. Version Control

Track changes with snapshots of your project's state.

• Save a version:

  bucket vs commit

• List saved versions:

  bucket vs history

• Rollback to a version:

  bucket vs rollback --id1 <commit-id> --id2 <commit-id2>

---

6. Clean Up

Destroy the .bucket setup if no longer needed:

bucket destroy

---

Example Workflow

1. Initialize a new project:

   bucket init

2. Create and switch to a feature branch:

   bucket branch create flask-dependency
   bucket branch switch flask-dependency

3. Add Flask dependency:

   bucket dep add --name flask --source https://pypi.org/project/flask --version 2.2.3 --install-command "pip install flask==2.2.3"

4. Commit the addition:

   bucket vs commit

5. Create a pull request to merge changes:

   bucket pr create --source flask-dependency --target main --description "Add Flask dependency to project."

6. Approve and merge the pull request:

   bucket pr approve 20242311 170224

---

Additional Help

Run the following for detailed command help:

bucket --help

---

Contributing

Feedback and contributions are welcome! Open issues or submit pull requests on the GitHub repository.

---

License

This project is licensed under the Makoschin Free Software License (MFSL) Version 2.0. See the source code headers for more details.