Skip to content

Enhanced README with visual improvements and better structure #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shivram9 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Enhanced README with visual improvements and better structure #28

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ef681a3
Enhanced README with visual improvements and better structure
shivram9 Sep 23, 2025
8921be3
Merge branch 'main' into update-readme
shivram9 Sep 23, 2025
50d3d08
Enhanced README
shivram9 Sep 23, 2025
1f94ae0
Merge branch 'AdmGenSameer:main' into update-readme
shivram9 Sep 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
266 changes: 154 additions & 112 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,22 @@
# archpkg-helper
# archpkg-helper 🧰
*A universal package helper for Linux distributions*

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
**archpkg-helper** is a cross-distro command-line utility that helps you **search for packages** and **generate install/remove commands** for native Linux package managers such as:

- `pacman` (Arch)
- `AUR`
- `apt` (Debian/Ubuntu)
- `dnf` (Fedora)
- `flatpak`
- `snap`

It aims to simplify software discovery and installation, regardless of which Linux distribution you use.

---

## 📚 Table of Contents

- [About](#about)
- [Features](#features)
Expand All @@ -14,130 +28,149 @@ A cross-distro command-line utility that helps you search for packages and gener
- [Contributing](#contributing)
- [License](#license)

## About
---

## 🔍 About

**archpkg-helper** is designed to work across Linux distributions. While originally inspired by Arch Linux, it automatically detects your system and generates the appropriate commands for the package manager available.

It’s suitable for:

- 🧑‍💻 Newcomers who aren’t familiar with Linux package managers
- 💡 Developers who work across multiple distros
- 🧠 Experienced users looking for a more unified workflow

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
- Cross-distro support (not limited to Arch)
- Clear, readable output and errors
- One-command setup via `install.sh`
✅ Search for packages and generate install commands for:

## Quick Start (install.sh)
- `pacman` (Arch)
- `AUR` (via AUR helpers)
- `apt` (Debian/Ubuntu)
- `dnf` (Fedora)
- `flatpak`
- `snap`

Install directly using the provided installer script.
✅ Cross-distro support (not limited to Arch)
✅ Clear, readable output and helpful error messages
✅ One-command setup via `install.sh`

From a cloned repository:
```sh
---

## ⚡ Quick Start (install.sh)

Install `archpkg-helper` using the one-line 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:
```sh
Or run directly from the web
bash
Copy code
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.

1) Install pipx
- Arch Linux:
```sh
sudo pacman -S pipx
pipx ensurepath
```
- Debian/Ubuntu:
```sh
sudo apt update
sudo apt install pipx
pipx ensurepath
```
- Fedora:
```sh
sudo dnf install pipx
pipx ensurepath
```

2) Install archpkg-helper with pipx
- Directly from GitHub:
```sh
pipx install git+https://github.com/AdmGenSameer/archpkg-helper.git
```
- From a local clone:
```sh
git clone https://github.com/AdmGenSameer/archpkg-helper.git
cd archpkg-helper
pipx install .
```

Upgrade later with:
```sh
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)

If you prefer pip, install in user scope to avoid system conflicts:
The installer ensures that Python, pip, and pipx are available.

You may be prompted for sudo to install missing dependencies.

📦 Installation (Recommended: pipx)
Modern Linux distros often protect system Python (via PEP 668), which makes pipx the preferred method for installing CLI tools.

🛠️ Step 1: Install pipx
<details> <summary>📦 Arch Linux</summary>
bash
Copy code
sudo pacman -S pipx
pipx ensurepath
</details> <details> <summary>📦 Debian / Ubuntu</summary>
bash
Copy code
sudo apt update
sudo apt install pipx
pipx ensurepath
</details> <details> <summary>📦 Fedora</summary>
bash
Copy code
sudo dnf install pipx
pipx ensurepath
</details>
🧰 Step 2: Install archpkg-helper
From GitHub:

bash
Copy code
pipx install git+https://github.com/AdmGenSameer/archpkg-helper.git
From a local clone:

bash
Copy code
git clone https://github.com/AdmGenSameer/archpkg-helper.git
cd archpkg-helper
pipx install .
🔄 To upgrade later:
bash
Copy code
pipx upgrade archpkg-helper
📌 After running pipx ensurepath, ensure your shell has ~/.local/bin in your PATH.

- From a local clone:
```sh
git clone https://github.com/AdmGenSameer/archpkg-helper.git
cd archpkg-helper
python3 -m pip install --user .
```
- Directly from GitHub:
```sh
python3 -m pip install --user git+https://github.com/AdmGenSameer/archpkg-helper.git
```
🐍 Alternative Installation (pip)
Use this only if pipx is not available. Install the tool in user scope to avoid system conflicts:

If your distro enforces PEP 668 protections for global installs, you may see errors. You can bypass with:
```sh
From a local clone:
bash
Copy code
git clone https://github.com/AdmGenSameer/archpkg-helper.git
cd archpkg-helper
python3 -m pip install --user .
Or directly from GitHub:
bash
Copy code
python3 -m pip install --user git+https://github.com/AdmGenSameer/archpkg-helper.git
⚠️ If your system enforces PEP 668 protections, you might see errors. To override:

bash
Copy code
python3 -m pip install --break-system-packages .
```
However, using pipx is strongly recommended instead of breaking system protections.

## Usage

After installation, the CLI is available as `archpkg`.

Examples:
```sh
# Search for a package across supported sources
However, using pipx is strongly recommended instead of bypassing system protections.

🚀 Usage
After installation, the CLI will be available as:

bash
Copy code
archpkg
Common examples:
bash
Copy code
# 🔍 Search for a package
archpkg search <package-name>

# Generate install command(s) for a package
# 📦 Get install command(s)
archpkg install <package-name>

# Generate removal command(s) for a package
# ❌ Get uninstall command(s)
archpkg remove <package-name>
```
You can also run:

Additional:
```sh
bash
Copy code
archpkg --help
archpkg --version
```

Replace `<package-name>` with the package you want to manage.
Replace <package-name> with the software you want (e.g. vlc, neofetch, etc.).

## File Structure
📁 File Structure
Project layout overview:

Top-level layout of this repository:
```
bash
Copy code
archpkg-helper/
├── archpkg/ # Core Python package code (CLI and logic)
├── install.sh # One-command installer script (uses pipx)
Expand All @@ -149,21 +182,30 @@ archpkg-helper/
├── __pycache__/ # Python bytecode cache (auto-generated)
├── archpkg_helper.egg-info/ # Packaging metadata (auto-generated)
└── archpy.egg-info/ # Packaging metadata (auto-generated)
```
📝 Some build folders appear only after running packaging/install commands.

🤝 Contributing
We welcome contributions from everyone! To contribute:

Fork the repository

Create a branch

Some metadata/build directories are generated during packaging and may not be present in fresh clones.
bash
Copy code
git checkout -b feature/my-feature
Make your changes

## Contributing
Commit with a clear message

Contributions are welcome! Please:
1. Fork the repository
2. Create a feature 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
bash
Copy code
git commit -m "Add: my new feature"
Push to your fork

Report bugs or request features via the [issue tracker](https://github.com/AdmGenSameer/archpkg-helper/issues).
Open a Pull Request

## License
You can also open issues for bugs or feature suggestions.

This project is licensed under the [Apache License 2.0](./LICENSE).
📄 License
This project is licensed under the Apache License 2.0.