From 5ca7409d989e99294fb424cf10f408de8c783f23 Mon Sep 17 00:00:00 2001 From: Shivram Date: Wed, 24 Sep 2025 06:54:12 +0530 Subject: [PATCH 1/2] added updated readme --- README.md | 203 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 142 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index aa08b8d..6b63e36 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,185 @@ # archpkg-helper -A command-line utility for simplifying package management on Linux distributions. This project aims to make installing, removing, and searching for packages easier, and welcomes contributions from the open source community. +A cross-distro command-line utility that helps you search for packages and generate install commands for native package managers (pacman, AUR, apt, dnf, flatpak, snap). It aims to make discovering and installing software on Linux simpler, regardless of your distribution. ## Table of Contents -- [About](#about) -- [Features](#features) -- [Installation](#installation) -- [Usage](#usage) -- [File Structure](#file-structure) -- [Contributing](#contributing) -- [License](#license) +- [About](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#about) +- [Features](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#features) +- [Quick Start (install.sh)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#quick-start-installsh) +- [Installation (Recommended: pipx)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#installation-recommended-pipx) +- [Alternative Installation (pip)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#alternative-installation-pip) +- [Usage](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#usage) +- [File Structure](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#file-structure) +- [Contributing](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#contributing) +- [License](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#license) ## About -archpkg-helper is designed for users who want an easier way to manage packages on Linux systems. While originally inspired by Arch Linux, this tool aims to work on any Linux distribution that supports Python and common package managers. Whether you’re new to Linux or a seasoned user, this tool offers simple commands for common package operations. +archpkg-helper is designed to work across Linux distributions. While originally inspired by Arch Linux, it detects your system and generates appropriate install commands for common package managers. It's suitable for both newcomers and experienced users who want a simpler way to search and install packages. ## Features -- Install, remove, and search for packages with simple commands -- Support for dependencies and AUR packages (coming soon) -- Easy-to-read output and error messages -- Not bound to Arch Linux—can be used on other Linux distros with compatible package managers +Search for packages and generate install commands for: +- pacman (Arch), AUR, apt (Debian/Ubuntu), dnf (Fedora), flatpak, snap +- Cross-distro support (not limited to Arch) +- Clear, readable output and errors +- One-command setup via install.sh -## Installation +## Quick Start (install.sh) -You can install archpkg-helper on any Linux distro. Here are the steps: +Install directly using the provided installer script. -### Prerequisites +From a cloned repository: -- Python 3.6 or newer -- `git` installed +```bash +git clone https://github.com/AdmGenSameer/archpkg-helper.git +cd archpkg-helper +bash install.sh +``` + +Or run directly from the web: + +```bash +curl -fsSL https://raw.githubusercontent.com/AdmGenSameer/archpkg-helper/main/install.sh | bash +# or +wget -qO- https://raw.githubusercontent.com/AdmGenSameer/archpkg-helper/main/install.sh | bash +``` + +Notes: + +- The installer ensures Python, pip, and pipx are available and installs the CLI via pipx. +- You may be prompted for sudo to install prerequisites on your distro. + +## Installation (Recommended: pipx) + +On Arch and many other distros, system Python may be "externally managed" (PEP 668), which prevents global pip installs. pipx installs Python CLIs into isolated environments and puts their executables on your PATH—this is the easiest, safest method. + +### Install pipx + +Arch Linux: +```bash +sudo pacman -S pipx +pipx ensurepath +``` + +Debian/Ubuntu: +```bash +sudo apt update +sudo apt install pipx +pipx ensurepath +``` + +Fedora: +```bash +sudo dnf install pipx +pipx ensurepath +``` + +### Install archpkg-helper with pipx + +Directly from GitHub: +```bash +pipx install git+https://github.com/AdmGenSameer/archpkg-helper.git +``` + +From a local clone: +```bash +git clone https://github.com/AdmGenSameer/archpkg-helper.git +cd archpkg-helper +pipx install . +``` + +Upgrade later with: + +```bash +pipx upgrade archpkg-helper +``` + +Ensure your shell session has pipx's bin path in PATH (pipx prints instructions after pipx ensurepath, typically ~/.local/bin). -### Steps +## Alternative Installation (pip) -```sh +If you prefer pip, install in user scope to avoid system conflicts: + +From a local clone: +```bash git clone https://github.com/AdmGenSameer/archpkg-helper.git cd archpkg-helper -pip install . +python3 -m pip install --user . +``` + +Directly from GitHub: +```bash +python3 -m pip install --user git+https://github.com/AdmGenSameer/archpkg-helper.git ``` -Or for development: +If your distro enforces PEP 668 protections for global installs, you may see errors. You can bypass with: -```sh -pip install -e . +```bash +python3 -m pip install --break-system-packages . ``` +However, using pipx is strongly recommended instead of breaking system protections. + ## Usage -After installing, use the following commands: +After installation, the CLI is available as archpkg. + +Examples: -```sh -archpkg-helper install -archpkg-helper remove -archpkg-helper search +```bash +# Search for a package across supported sources +archpkg search + +# Generate install command(s) for a package +archpkg install + +# Generate removal command(s) for a package +archpkg remove +``` + +Additional: + +```bash +archpkg --help +archpkg --version ``` -Replace `` with the package you want to manage. +Replace with the package you want to manage. ## File Structure +Top-level layout of this repository: + ``` archpkg-helper/ -│ -├── archpkg_helper/ # Main Python package -│ ├── __init__.py -│ ├── cli.py # Command-line interface implementation -│ ├── core.py # Core logic for package management -│ └── utils.py # Utility functions -│ -├── tests/ # Unit tests -│ ├── test_cli.py -│ └── test_core.py -│ -├── setup.py # Python packaging configuration -├── LICENSE # Project license (Apache 2.0) -├── README.md # This file -└── CONTRIBUTING.md # Contribution guidelines +├── archpkg/ # Core Python package code (CLI and logic) +├── install.sh # One-command installer script (uses pipx) +├── pyproject.toml # Build/metadata configuration +├── setup.py # Packaging configuration (entry points, deps) +├── LICENSE # Project license (Apache 2.0) +├── README.md # Project documentation (this file) +├── build/ # Build artifacts (may appear after builds) +├── __pycache__/ # Python bytecode cache (auto-generated) +├── archpkg_helper.egg-info/ # Packaging metadata (auto-generated) +└── archpy.egg-info/ # Packaging metadata (auto-generated) ``` -## Contributing - -We welcome contributions! Please read our [`CONTRIBUTING.md`](./CONTRIBUTING.md) for guidelines. +Some metadata/build directories are generated during packaging and may not be present in fresh clones. -### How to Contribute +## Contributing -1. Fork the repository. -2. Create a branch: `git checkout -b feature-branch` -3. Make your changes and commit: `git commit -m "Describe your changes"` -4. Push to your fork: `git push origin feature-branch` -5. Open a Pull Request. +Contributions are welcome! Please: -#### Issues +- Fork the repository +- Create a feature branch: git checkout -b feature-branch +- Make your changes and commit: git commit -m "Describe your changes" +- Push to your fork: git push origin feature-branch +- Open a Pull Request -Report bugs or request features [here](https://github.com/AdmGenSameer/archpkg-helper/issues). +Report bugs or request features via the [issue tracker](https://github.com/AdmGenSameer/archpkg-helper/issues). ## License -This project is licensed under the [Apache License 2.0](./LICENSE). - ---- - -*Happy hacking!* \ No newline at end of file +This project is licensed under the [Apache License 2.0](https://github.com/AdmGenSameer/archpkg-helper/blob/main/LICENSE). \ No newline at end of file From b8571c115f3432d4903964da20fcc8f12dbff8f1 Mon Sep 17 00:00:00 2001 From: Shivram Date: Fri, 26 Sep 2025 12:29:29 +0530 Subject: [PATCH 2/2] updated the readme section --- README.md | 104 +++++++++++++++--------------------------------------- 1 file changed, 29 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 6b63e36..6df5fcd 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,24 @@ -# archpkg-helper +# 🚀 archpkg-helper A cross-distro command-line utility that helps you search for packages and generate install commands for native package managers (pacman, AUR, apt, dnf, flatpak, snap). It aims to make discovering and installing software on Linux simpler, regardless of your distribution. -## Table of Contents +## 📑 Table of Contents -- [About](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#about) -- [Features](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#features) -- [Quick Start (install.sh)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#quick-start-installsh) -- [Installation (Recommended: pipx)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#installation-recommended-pipx) -- [Alternative Installation (pip)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#alternative-installation-pip) -- [Usage](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#usage) -- [File Structure](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#file-structure) -- [Contributing](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#contributing) -- [License](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#license) +- [🎯 About](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#about) +- [✨ Features](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#features) +- [⚡Quick Start (install.sh)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#quick-start-installsh) +- [📦 Installation (Recommended: pipx)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#installation-recommended-pipx) +- [🔧 Alternative Installation (pip)](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#alternative-installation-pip) +- [🎮 Usage](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#usage) +- [📁 File Structure](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#file-structure) +- [🤝 Contributing](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#contributing) +- [📄 License](https://github.com/AdmGenSameer/archpkg-helper?tab=readme-ov-file#license) -## About +## 🎯 About archpkg-helper is designed to work across Linux distributions. While originally inspired by Arch Linux, it detects your system and generates appropriate install commands for common package managers. It's suitable for both newcomers and experienced users who want a simpler way to search and install packages. -## Features +## ✨ Features Search for packages and generate install commands for: - pacman (Arch), AUR, apt (Debian/Ubuntu), dnf (Fedora), flatpak, snap @@ -26,109 +26,68 @@ Search for packages and generate install commands for: - Clear, readable output and errors - One-command setup via install.sh -## Quick Start (install.sh) - +⚡Quick Start (install.sh) Install directly using the provided installer script. From a cloned repository: -```bash git clone https://github.com/AdmGenSameer/archpkg-helper.git cd archpkg-helper bash install.sh -``` - -Or run directly from the web: +🌐 Or run directly from the web: -```bash curl -fsSL https://raw.githubusercontent.com/AdmGenSameer/archpkg-helper/main/install.sh | bash # or wget -qO- https://raw.githubusercontent.com/AdmGenSameer/archpkg-helper/main/install.sh | bash -``` - -Notes: +⚠️Notes: -- The installer ensures Python, pip, and pipx are available and installs the CLI via pipx. -- You may be prompted for sudo to install prerequisites on your distro. - -## Installation (Recommended: pipx) - -On Arch and many other distros, system Python may be "externally managed" (PEP 668), which prevents global pip installs. pipx installs Python CLIs into isolated environments and puts their executables on your PATH—this is the easiest, safest method. - -### Install pipx +The installer ensures Python, pip, and pipx are available and installs the CLI via pipx. +You may be prompted for sudo to install prerequisites on your distro. +📦 Installation (Recommended: pipx) +On Arch and many other distros, system Python may be “externally managed” (PEP 668), which prevents global pip installs. pipx installs Python CLIs into isolated environments and puts their executables on your PATH—this is the easiest, safest method. +Install pipx Arch Linux: -```bash sudo pacman -S pipx pipx ensurepath -``` - Debian/Ubuntu: -```bash sudo apt update sudo apt install pipx pipx ensurepath -``` - Fedora: -```bash sudo dnf install pipx pipx ensurepath -``` - -### Install archpkg-helper with pipx - +Install archpkg-helper with pipx Directly from GitHub: -```bash pipx install git+https://github.com/AdmGenSameer/archpkg-helper.git -``` - From a local clone: -```bash git clone https://github.com/AdmGenSameer/archpkg-helper.git cd archpkg-helper pipx install . -``` - Upgrade later with: -```bash pipx upgrade archpkg-helper -``` - -Ensure your shell session has pipx's bin path in PATH (pipx prints instructions after pipx ensurepath, typically ~/.local/bin). - -## Alternative Installation (pip) +Ensure your shell session has pipx’s bin path in PATH (pipx prints instructions after pipx ensurepath, typically ~/.local/bin). +🔧Alternative Installation (pip) If you prefer pip, install in user scope to avoid system conflicts: From a local clone: -```bash git clone https://github.com/AdmGenSameer/archpkg-helper.git cd archpkg-helper python3 -m pip install --user . -``` - Directly from GitHub: -```bash python3 -m pip install --user git+https://github.com/AdmGenSameer/archpkg-helper.git -``` - If your distro enforces PEP 668 protections for global installs, you may see errors. You can bypass with: -```bash python3 -m pip install --break-system-packages . -``` - However, using pipx is strongly recommended instead of breaking system protections. -## Usage - +🎮 Usage After installation, the CLI is available as archpkg. Examples: -```bash # Search for a package across supported sources archpkg search @@ -137,18 +96,13 @@ archpkg install # Generate removal command(s) for a package archpkg remove -``` - Additional: -```bash archpkg --help archpkg --version -``` - Replace with the package you want to manage. -## File Structure +## 📁File Structure Top-level layout of this repository: @@ -166,9 +120,9 @@ archpkg-helper/ └── archpy.egg-info/ # Packaging metadata (auto-generated) ``` -Some metadata/build directories are generated during packaging and may not be present in fresh clones. +💡Some metadata/build directories are generated during packaging and may not be present in fresh clones. -## Contributing +## 🤝 Contributing Contributions are welcome! Please: @@ -180,6 +134,6 @@ Contributions are welcome! Please: Report bugs or request features via the [issue tracker](https://github.com/AdmGenSameer/archpkg-helper/issues). -## License +## 📄 License This project is licensed under the [Apache License 2.0](https://github.com/AdmGenSameer/archpkg-helper/blob/main/LICENSE). \ No newline at end of file