Skip to content

added a new readme file #38

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 2 commits into
base: main
Choose a base branch
from
Open

added a new readme file #38

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e2bcb34
addede a new readme file
shivram9 Sep 26, 2025
bed7cc3
Merge branch 'main' into newreadme
shivram9 Sep 26, 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
168 changes: 69 additions & 99 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,121 +1,93 @@
# 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](#about)
- [Features](#features)
- [Quick Start (install.sh)](#quick-start-installsh)
- [Installation (Recommended: pipx)](#installation-recommended-pipx)
- [Alternative Installation (pip)](#alternative-installation-pip)
- [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
## 🎯 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.
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
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`

## Quick Start (install.sh)
- One-command setup via install.sh

⚡Quick Start (install.sh)
Install directly using the provided installer script.

From a cloned repository:
```sh

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:
```sh
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)
⚠️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 .
```

Install pipx
Arch Linux:
sudo pacman -S pipx
pipx ensurepath
Debian/Ubuntu:
sudo apt update
sudo apt install pipx
pipx ensurepath
Fedora:
sudo dnf install pipx
pipx ensurepath
Install archpkg-helper with pipx
Directly from GitHub:
pipx install git+https://github.com/AdmGenSameer/archpkg-helper.git
From a local clone:
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)
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:

- 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
```

From a local clone:
git clone https://github.com/AdmGenSameer/archpkg-helper.git
cd archpkg-helper
python3 -m pip install --user .
Directly from GitHub:
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:
```sh

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`.
🎮 Usage
After installation, the CLI is available as archpkg.

Examples:
```sh

# Search for a package across supported sources
archpkg search <package-name>

Expand All @@ -124,19 +96,16 @@ archpkg install <package-name>

# Generate removal command(s) for a package
archpkg remove <package-name>
```

Additional:
```sh

archpkg --help
archpkg --version
```
Replace <package-name> with the package you want to manage.

Replace `<package-name>` with the package you want to manage.

## File Structure
## 📁File Structure

Top-level layout of this repository:

```
archpkg-helper/
├── archpkg/ # Core Python package code (CLI and logic)
Expand All @@ -151,19 +120,20 @@ 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:
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

- 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 via the [issue tracker](https://github.com/AdmGenSameer/archpkg-helper/issues).

## License
## 📄 License

This project is licensed under the [Apache License 2.0](./LICENSE).
This project is licensed under the [Apache License 2.0](https://github.com/AdmGenSameer/archpkg-helper/blob/main/LICENSE).