191 lines
4.7 KiB
Markdown
191 lines
4.7 KiB
Markdown
# getpkg - Package Manager for Dropshell Tools
|
|
|
|
getpkg is a command-line package manager that simplifies tool installation, management, and publishing for the dropshell ecosystem. Tools are installed to `~/.getpkg/` with executable symlinks in `~/.local/bin/getpkg/` and automatically added to your PATH with bash completion.
|
|
|
|
## Installation
|
|
|
|
Install getpkg with a single command:
|
|
|
|
```bash
|
|
curl https://getbin.xyz/getpkg-install | bash
|
|
```
|
|
|
|
After installation, restart your shell or run `source ~/.bashrc` to enable the new PATH and completion settings.
|
|
|
|
## Basic Usage
|
|
|
|
### Installing Tools
|
|
|
|
Install any tool from the getpkg registry:
|
|
|
|
```bash
|
|
# Install a tool
|
|
getpkg install whatsdirty
|
|
```
|
|
|
|
### Managing Installed Tools
|
|
|
|
```bash
|
|
# List all available commands
|
|
getpkg help
|
|
|
|
# Update all installed tools
|
|
getpkg update
|
|
|
|
# Uninstall a tool
|
|
getpkg uninstall whatsdirty
|
|
|
|
# Check getpkg version
|
|
getpkg version
|
|
```
|
|
|
|
## Available Commands
|
|
|
|
### Core Package Management
|
|
|
|
- **`getpkg install <tool_name>`** - Install or update a tool
|
|
- **`getpkg uninstall <tool_name>`** - Remove an installed tool
|
|
- **`getpkg update`** - Update getpkg and all installed tools
|
|
|
|
### Publishing (Requires SOS_WRITE_TOKEN)
|
|
|
|
- **`getpkg publish <tool_name[:ARCH]> <folder>`** - Upload a tool to getpkg.xyz
|
|
- **`getpkg unpublish <tool_name[:ARCH]>`** - Remove a published tool
|
|
- **`getpkg unpublish <hash>`** - Remove a published tool by hash
|
|
|
|
### Development Tools
|
|
|
|
- **`getpkg create <tool_name> <directory>`** - Create a new tool project
|
|
- **`getpkg hash <file_or_directory>`** - Calculate hash of files/directories
|
|
|
|
### Information
|
|
|
|
- **`getpkg version`** - Show getpkg version
|
|
- **`getpkg help`** - Show detailed help
|
|
- **`getpkg autocomplete`** - Show available commands for completion
|
|
|
|
## How It Works
|
|
|
|
### Installation Process
|
|
|
|
When you install a tool, getpkg:
|
|
|
|
1. **Downloads** the tool archive from getpkg.xyz
|
|
2. **Extracts** it to `~/.getpkg/<tool_name>/`
|
|
3. **Creates symlinks** for all executables in `~/.local/bin/getpkg/`
|
|
4. **Ensures PATH** includes `~/.local/bin/getpkg` (one-time setup)
|
|
5. **Enables completion** for the tool
|
|
6. **Runs setup** if a `setup_script.sh` exists
|
|
7. **Stores metadata** in `~/.config/getpkg/<tool_name>.json`
|
|
|
|
### Architecture Support
|
|
|
|
getpkg supports multiple architectures:
|
|
- `x86_64` (Intel/AMD 64-bit)
|
|
- `aarch64` (ARM 64-bit)
|
|
- `universal` (cross-platform tools)
|
|
|
|
Tools are automatically downloaded for your architecture, with fallback to universal versions.
|
|
|
|
### File Locations
|
|
|
|
- **Tool files**: `~/.getpkg/<tool_name>/` (actual tool installation)
|
|
- **Executable symlinks**: `~/.local/bin/getpkg/` (in your PATH)
|
|
- **Configuration**: `~/.config/getpkg/`
|
|
- **PATH setup**: `~/.bashrc_getpkg` (sourced by `~/.bashrc`)
|
|
|
|
## Examples
|
|
|
|
### Installing Popular Tools
|
|
|
|
```bash
|
|
# Install development tools
|
|
getpkg whatsdirty # Fast grep alternative
|
|
getpkg fd # Fast find alternative
|
|
getpkg bat # Cat with syntax highlighting
|
|
|
|
# Install system utilities
|
|
getpkg whatsdirty # Check git repo status
|
|
getpkg sos # Simple object storage client
|
|
```
|
|
|
|
### Publishing Your Own Tools
|
|
|
|
```bash
|
|
# Set your publishing token
|
|
export SOS_WRITE_TOKEN="your-token-here"
|
|
|
|
# Create a new tool project
|
|
getpkg create mytool ./mytool-project
|
|
|
|
# Publish architecture-specific build
|
|
getpkg publish mytool:x86_64 ./build/
|
|
|
|
# Publish universal tool
|
|
getpkg publish mytool ./build/
|
|
|
|
# Remove published tool
|
|
getpkg unpublish mytool:x86_64
|
|
```
|
|
|
|
### Development Workflow
|
|
|
|
```bash
|
|
# Create tool structure
|
|
getpkg create awesome-tool ./awesome-tool
|
|
cd awesome-tool
|
|
|
|
# Build your tool...
|
|
# Add executable to the directory
|
|
|
|
# Test locally
|
|
./awesome-tool --version
|
|
|
|
# Publish when ready
|
|
getpkg publish awesome-tool:x86_64 .
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
- **`SOS_WRITE_TOKEN`** - Authentication token for publishing tools
|
|
|
|
## Troubleshooting
|
|
|
|
### Tool Not Found
|
|
If a tool isn't found after installation, ensure your shell has loaded the new PATH:
|
|
```bash
|
|
source ~/.bashrc
|
|
```
|
|
|
|
### Permission Issues
|
|
getpkg installs to your home directory and doesn't require root access. If you encounter permission issues, check that `~/.local/bin/` is writable.
|
|
|
|
### Network Issues
|
|
All tools are downloaded from `getpkg.xyz`. Ensure you have internet connectivity and the domain is accessible.
|
|
|
|
## Development
|
|
|
|
### Building getpkg
|
|
|
|
```bash
|
|
# Build debug version
|
|
cd getpkg && ./build.sh
|
|
|
|
# Run tests
|
|
cd getpkg && ./test.sh
|
|
|
|
# Publish (requires SOS_WRITE_TOKEN)
|
|
cd getpkg && ./publish.sh
|
|
```
|
|
|
|
### Tool Development
|
|
|
|
When creating tools for getpkg:
|
|
|
|
1. Create a directory with your tool binary
|
|
2. Optionally include a `setup_script.sh` for post-install setup
|
|
3. The tool should support `version` and `autocomplete` subcommands
|
|
4. Use `getpkg publish` to upload to the registry
|
|
|
|
For more details, see the development documentation in each tool's directory.
|