pony-git 0.1.0
Git manager CLI
License: MIT
Requires Python: >=3.11
Keywords: cli, git, project, developer-tools

# 🐴 Pony Git Manager (pony-git)

[![Python Version](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Development Status](https://img.shields.io/badge/status-alpha-orange.svg)]()

CLI-обёртка над Git, которая упрощает и автоматизирует типичные рабочие процессы. Это не замена Git, а набор высокоуровневых команд, которые объединяют несколько операций в одну и добавляют проверки безопасности.

---

## 📋 Содержание

- [Что это?](#-что-это)
- [Зачем?](#-зачем)
- [Установка](#-установка)
- [Быстрый старт](#-быстрый-старт)
- [Доступные команды](#-доступные-команды)
- [Примеры использования](#-примеры-использования)
- [Чем НЕ является](#-чем-не-является)
- [Требования](#-требования)
- [Разработка](#-разработка)
- [Лицензия](#-лицензия)

---

## 🎯 Что это?

**pony-git** — умный помощник для повседневной работы с Git, который:

- ✅ Объединяет `git add .` + `git commit` в одну команду
- ✅ Проверяет наличие `.gitignore` перед коммитом
- ✅ Предоставляет встроенные подсказки workflow'ов
- ✅ Упрощает работу с remote, tags и branches
- ✅ Добавляет защиту от типичных ошибок

---

## 💡 Зачем?

### Проблемы, которые решает pony-git:

| Проблема | Решение pony-git |
|----------|------------------|
| Множество команд для простых операций | Одна команда вместо 3-5 |
| Случайные коммиты без `.gitignore` | Автоматическая проверка + `--force` опция |
| Забывание best practices | Встроенные подсказки (`pony-git info`) |
| Разные подходы в команде | Стандартизированный workflow |
| Ошибки из-за невнимательности | Валидация перед выполнением |

### Целевая аудитория:

- 🎓 **Начинающие разработчики** — упрощение изучения Git
- 🚀 **Опытные разработчики** — автоматизация рутинных операций
- 👥 **Команды** — единый процесс работы с репозиторием

---

## 📦 Установка
> Доступно после публикации первого релиза.

### Из PyPI
```bash
pip install pony-git
```

### Проверка Установки
```bash
pony-git version
```

---
## 🚀 Быстрый старт

### Первый push в новый репозиторий
```bash
# Подсказка по workflow
pony-git info
# Выполнение команд
pony-git init
pony-git add -m "Initial commit"
pony-git branch -M <branch_name>
pony-git remote add origin https://github.com/username/repo.git
pony-git push -M
```

### Обновление существующего проекта
```bash
# Подсказка по обновлению
pony-git info --update
# Выполнение
pony-git status
pony-git add -m "Добавлена новая функция"
pony-git tag -a v1.0.1 -m "Патч релиз" # опционально
pony-git push
pony-git push --tags # если создавали тег
```

---
## 📚 Доступные команды

### Основные операции

| Команда | Описание | Пример |
|---------|----------|--------|
| `init` | Инициализация Git-репозитория | `pony-git init` |
| `add` | Добавление файлов + коммит | `pony-git add -m "Fix bug"` |
| `push` | Отправка изменений | `pony-git push` |
| `status` | Статус репозитория | `pony-git status` |
| `version` | Версия Git | `pony-git version` |

### Управление ветками и тегами

| Команда | Описание | Пример |
|---------|----------|--------|
| `branch` | Создание ветки | `pony-git branch -M main` |
| `tag` | Создание аннотированного тега | `pony-git tag -a v1.0.0 -m "Release"` |

### Управление remote

| Команда | Описание | Пример |
|---------|----------|--------|
| `remote list` | Список удалённых репозиториев | `pony-git remote list -v` |
| `remote add` | Добавление remote | `pony-git remote add origin <URL>` |
| `remote remove` | Удаление remote | `pony-git remote remove origin` |

### Утилиты

| Команда | Описание | Пример |
|---------|----------|--------|
| `info` | Подсказки по workflow | `pony-git info` / `pony-git info --update` |
| `remove` | Удаление файлов из Git | `pony-git remove file.txt` |

---

## 💻 Примеры использования

### 1. Работа с `.gitignore`
```bash
# ❌ Ошибка: нет .gitignore
pony-git add -m "Test"
# Error: .gitignore not found. Use --force to proceed.
# ✅ Принудительный коммит (с предупреждением)
pony-git add -m "Test" --force
# Warning: .gitignore not found
# ✅ Создайте .gitignore и всё будет работать
echo "*.pyc" > .gitignore
pony-git add -m "Test"
```

### 2. Статус репозитория
```bash
# Короткий формат (по умолчанию)
pony-git status
# Машиночитаемый формат
pony-git status --porcelain
```

### 3. Push с тегами
```bash
# Обычный push
pony-git push
# Push с тегами (одна команда)
pony-git push --tags
```

### 4. Удаление файлов
```bash
# Удалить из индекса, но оставить в файловой системе
pony-git remove secrets.txt
# Удалить полностью
pony-git remove secrets.txt --force
```

### 5. Работа вне Git-репозитория
```bash
cd /tmp/not-a-repo
pony-git status
# Error: Git repository not found
```

---

## ⚠️ Чем НЕ является

### ❌ Это НЕ замена Git

- Требует установленный Git в системе
- Выполняет Git-команды через `subprocess`
- Не переопределяет Git-функционал

### ❌ Это НЕ полноценный Git-клиент

- **Ограниченный набор команд**: только частые операции
- **Нет сложных сценариев**: `rebase`, `cherry-pick`, `bisect`, `stash`, `merge`
- **Для продвинутых задач**: используйте оригинальный Git

### ❌ Это НЕ GUI-приложение

- Только CLI (командная строка)
- Нет визуализации истории
- Нет графического интерфейса

### ❌ Это НЕ полная автоматизация

- Не разрешает конфликты автоматически
- Не заменяет понимание основ Git
- Не управляет pull-requests, issues, CI/CD

### ⚠️ Это НЕ production-ready (пока)

- **Версия**: 0.1.0 (Alpha)
- Ограниченная обработка edge cases
- Нужно больше тестирования в продакшене

---

## 🔧 Требования

- **Python**: >= 3.11
- **Git**: любая современная версия
- **OS**: Windows, Linux, macOS (кроссплатформенный)

---

## 🛠️ Разработка

### Установка для разработки
```bash
# Клонирование
git clone https://github.com/PonyPaPony/PonyGM.git
cd PonyGM
# Создание виртуального окружения
python -m venv venv
source venv/bin/activate # Linux/macOS
# venv\Scripts\activate # Windows
# Установка зависимостей
pip install -e .
pip install -r requirements.txt
```

### Запуск тестов
```bash
# Все тесты
pytest
# С покрытием
pytest --cov=pony_git
# Конкретный модуль
pytest pony_git/tests/test_handlers_add.py
```

### Структура проекта
```
pony_git/
├── parsers/ # Парсинг CLI-аргументов
│  ├── arguments.py # Определения аргументов
│  ├── builder.py # Построение главного парсера
│  └── register.py # Регистрация подкоманд
├── tests/ # Unit и integration тесты
├── config.py # Конфигурация команд 
├── exceptions.py # Кастомные исключения
├── handlers.py # Логика обработки команд
├── main.py # Точка входа
├── runner.py # Выполнение Git-команд
└── validators.py # Валидация окружения
```
---

## 📝 Лицензия
Этот проект распространяется под лицензией MIT. Подробности в файле [LICENSE](LICENSE).

```
MIT License
Copyright (c) 2026 PonyPaPony (Denis)
```
---

## 🔗 Ссылки

- **GitHub**: [PonyPaPony/PonyGM](https://github.com/PonyPaPony/PonyGM)
- **Issues**: [Сообщить о проблеме](https://github.com/PonyPaPony/PonyGM/issues)
- **Автор**: [PonyPaPony](https://github.com/PonyPaPony)

---

## 🎉 Благодарности

Спасибо всем, кто тестирует и улучшает этот проект!

**Разработано с 🐴 от PonyPaPony**