pluck-cli 0.6.0

Pluck git repos from any forge — auto-detect, auto-install, done!

Note: Development and CI run on GitLab; this GitHub repo is a mirror.

• Quick Start
• How It Works
• Features
• Commands
• Flags
• Installation
• Configuration
• Project Structure
• Development

🚀 Quick Start

# Install from any git forge — one command, zero fuss
pluck install https://github.com/user/repo
pluck install https://gitlab.com/user/project
pluck install https://codeberg.org/user/repo
pluck install https://bitbucket.org/owner/repo

# That's it. Pluck detects the project type and installs it.

🔄 How It Works

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│  Any git URL    │────▶│  Clone to    │────▶│  Detect Method  │────▶│  Install     │
│  (any forge)    │     │  Temp Dir    │     │  (Auto-detect)  │     │  (8 methods) │
└─────────────────┘     └──────────────┘     └─────────────────┘     └──────────────┘
                                                                         │
┌─────────────────┐     ┌──────────────┐                                │
│   Post-Install  │◀────│  Register    │◀───────────────────────────────┘
│   Hook (opt)    │     │  App         │
└─────────────────┘     └──────────────┘
         │
         ▼
┌─────────────────┐
│  Summary +      │
│  Cleanup        │
└─────────────────┘

Install Methods

✨ Features

Installation

• 🔗 Any git forge — Install from GitHub, GitLab, Codeberg, Bitbucket, SourceHut, Gitea, Gogs, Pagure, Forgejo, self-hosted, or any git URL
• 🔍 Auto-detection — Automatically detects project type and install method
• 📦 Batch install — Install multiple repositories in one command
• ⚡ Shallow clone — --shallow for faster downloads
• 🏷️ Branch/tag support — --ref to install specific versions
• 🎯 Force method — --method to override auto-detection
• ⏱️ Timeout & retry — --timeout and --retries for flaky connections

Management

• 📋 List apps — See all installed applications with disk size
• 🔄 Update apps — Re-install from original URL
• 🗑️ Uninstall — Remove apps with safety guards
• ✅ Verify — Check installed apps integrity
• 🧹 Clean — Remove orphaned registry entries
• 📊 Stats — Installation statistics and method breakdown
• 🌐 Multi-forge search — Search GitHub, GitLab, or Codeberg with --forge
• 🖱️ Browser right-click — Optional extension + protocol handler to install from any page
• 📤 Export/Import — Migrate registry between machines

Configuration

• 📁 Custom directory — --dir to override default install location
• ⚙️ User config — Persistent settings via config file
• 🎨 JSON output — --json for machine-readable output
• 🚫 No colors — --no-color for clean terminal output
• 🔇 Non-interactive — --yes for scripting
• 🐳 Docker support — Containerized installation
• 📖 Man page — man pluck for offline docs
• 🔧 Post-install hooks — Custom scripts after each install

🌐 Supported Forges

Any git hosting platform that follows the standard host/owner/repo URL pattern works — no plugin or config needed.

📖 Commands

🏷️ Flags

📥 Installation

From Source

# Clone the repository (GitLab is canonical - see note above; this repo is a mirror)
git clone https://gitlab.com/mabodu/pluck.git
cd pluck

# Install via pip
pip install -e .

# Or run directly
./src/pluck.py install https://gitlab.com/user/project

Via pip

pip install pluck-cli

Via Docker

docker build -t pluck .
docker run pluck install https://gitlab.com/user/project

⚙️ Configuration

Default Paths

User Config File

{
  "install_dir": "/custom/path",
  "method_priority": ["script", "python", "node", "go", "rust", "make", "binary", "download"]
}

Manage via CLI:

pluck config install_dir ~/Apps
pluck config method_priority '["python","node","binary","download"]'

Post-Install Hooks

Create ~/.config/pluck/hooks/post-install.sh to run custom scripts after each install.

Available environment variables:

• $PLUCK_APP — Repository name
• $PLUCK_PATH — Installation path
• $PLUCK_METHOD — Install method used

🖱️ Browser Integration

Pluck includes a right-click context menu integration. Install a repo from any forge without leaving your browser.

Quick Setup

# 1. Register the pluck:// protocol handler on your OS
bash scripts/install-protocol-handler.sh

# 2. Load the browser extension (Chrome/Chromium/Brave/Edge)
#    Open chrome://extensions → Developer mode → Load unpacked
#    Select assets/browser-extension/

# 3. Right-click any git repo link → "Install with pluck"

Works with GitHub, GitLab, Codeberg, Bitbucket, SourceHut — any forge.

No Extension? Use the Bookmarklet

If you prefer not to install an extension, create a bookmark with this URL:

javascript:location.href='pluck://install?url='+encodeURIComponent(location.href)

When you're on a git repo page, click the bookmark to install it.

How It Works

The protocol handler is a small shell script (scripts/pluck-protocol-handler.sh) that receives pluck://install?url=... calls from the browser, decodes the URL, and runs pluck install <url>. The browser extension adds the right-click menu item that triggers this protocol call.

📁 Project Structure

pluck/
├── src/
│   ├── pluck.py                # Main application (~2400 lines)
│   └── gh_install.py           # Backward-compat alias (imports pluck)
├── tests/
│   └── test_pluck.py           # Test suite (132 tests)
├── assets/
│   ├── images/                 # Logo and illustrations
│   └── browser-extension/      # Chrome/Chromium right-click extension
├── scripts/
│   ├── pluck-protocol-handler.sh    # pluck:// URL handler
│   └── install-protocol-handler.sh  # Protocol registration
├── docs/
│   └── IMPLEMENTATION.md      # Implementation details
├── man/
│   ├── pluck.1                # Man page
│   └── gh-install.1           # Legacy man page (kept for backward compat)
├── .github/
│   └── workflows/
│       └── release.yml        # Build wheel + binaries, publish to PyPI + GitHub Releases
├── README.md                  # This file
├── CHANGELOG.md               # Version history
├── CONTRIBUTING.md            # Developer guide
├── LICENSE                    # MIT License
├── Dockerfile                 # Container image
├── pyproject.toml             # Package config
├── .pre-commit-config.yaml    # Pre-commit hooks
├── .gitignore                 # Git ignore patterns
└── .dockerignore              # Docker ignore patterns

🛠️ Development

# Install dev dependencies
pip install pytest ruff

# Run tests
python -m pytest tests/ -v

# Run linter
ruff check src/ tests/

# Install pre-commit hooks
pip install pre-commit
pre-commit install

Test Coverage

132 tests passing across 31 test classes:
├── TestParseRepoUrl (22 tests)
├── TestGistUrl (7 tests) — includes GitLab snippets
├── TestDetectInstallMethod (17 tests)
├── TestSharedPaths (2 tests)
├── TestValidMethods (2 tests)
├── TestSanitizeRepoName (4 tests)
├── TestIsExecutable (6 tests)
├── TestGetDiskSize (3 tests)
├── TestParseArgs (10 tests)
├── TestDryRun (1 test)
├── TestRegistryOperations (3 tests)
├── TestUpdateApp (2 tests)
├── TestInfoApp (2 tests)
├── TestDoctor (2 tests)
├── TestConfigCommand (2 tests)
├── TestExportImport (4 tests)
├── TestVerifyApps (3 tests)
├── TestStatsCommand (2 tests)
├── TestFormatBytes (5 tests)
├── TestExtractGlobalFlags (5 tests)
├── TestDownloadAndInstallMocked (4 tests)
├── TestParseArgsMissingFlagValue (6 tests) — regression: flags with missing values
├── TestRegistryAtomicWrite (5 tests) — regression: atomic writes + locking across all registry ops
├── TestInstallPythonSymlink (2 tests) — regression: symlink bug + directory-guard
├── TestSafeTarMembers (2 tests) — regression: CVE-2007-4559 + backslash bypass
├── TestProtocolHandlerUrlParsing (4 tests) — regression: multi-param URL parsing
├── TestReleaseInstallFallback (1 test) — regression: --release fallback to clone
└── TestInstallMakeFallback (1 test) — regression: uncaught CalledProcessError on make failure

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read the Contributing Guide for details on our code of conduct and the process for submitting pull requests.

Made with ❤️ for non-technical users everywhere