Metadata-Version: 2.4
Name: gitmate_benjamin
Version: 0.2.0
Summary: A terminal-based Git assistant
Project-URL: Homepage, https://github.com/JohnEdwinR/gitmate
Project-URL: Repository, https://github.com/JohnEdwinR/gitmate
Project-URL: Issues, https://github.com/JohnEdwinR/gitmate/issues
Author: John Rajaratnam
License-Expression: MIT
License-File: LICENSE
Keywords: assistant,cli,developer-tools,git,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Requires-Dist: questionary>=2
Requires-Dist: rich>=13
Requires-Dist: typer[all]>=0.12
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest-mock>=3; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# GitMate

**A terminal-based Git assistant that helps you choose, understand, and safely run the correct Git commands.**

[![PyPI version](https://img.shields.io/pypi/v/gitmate?color=blue&label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/gitmate/)
[![Python](https://img.shields.io/pypi/pyversions/gitmate?color=green&label=Python&logo=python&logoColor=white)](https://pypi.org/project/gitmate/)
[![License](https://img.shields.io/pypi/l/gitmate?color=orange&label=License)](https://github.com/JohnEdwinR/gitmate/blob/main/LICENSE)
[![Tests](https://img.shields.io/badge/tests-72%20passing-brightgreen)](#testing)

---

GitMate inspects your repository, detects its state, and guides you through Git workflows using plain language — no memorizing commands required.

</div>

---

## The Problem

Git is powerful, but many developers struggle with:

| Pain Point | Example |
|-----------|---------|
| Forgetting commands | "How do I undo the last commit but keep files?" |
| Risky operations | Not knowing `git push --force` can delete teammates' work |
| cryptic errors | `fatal: The current branch has no upstream branch` |
| Similar commands | `git reset --soft` vs `--mixed` vs `--hard` — what's the difference? |
| History rewriting | Amending a pushed commit breaks everyone's clone |

**GitMate solves this** by reading your actual repository state and recommending the right command with explanations and safety warnings.

---

## Features

### Repository Awareness

GitMate inspects your repo before recommending anything:

```
+---------------------------------- GitMate ----------------------------------+
|   Branch:               feature/login                                       |
|   Changes:              2 staged, 3 modified, 1 untracked                  |
|   Remote:               origin (https://github.com/user/repo.git)          |
|   Upstream:             origin/feature/login (2 ahead, 1 behind)           |
|   Recent:               a1b2c3d Fix login validation                       |
|                         e4f5g6h Add user model                              |
+-----------------------------------------------------------------------------+
```

### Guided Interactive Mode

Run `gitmate` and choose from categories instead of remembering commands:

```
What do you want to do?

  Save changes
  Undo changes
  Commit management
  Branch management
  Remote synchronization
  Stash management
  Repository information
```

Then drill into specific actions:

```
Select an action (Commit management):
  Create a commit
  Change the latest commit message
  Add files to the latest commit
  Initialize a repository
```

### Command Preview & Safety

Every command is shown before execution with risk classification:

```
+--------------------------- Command Preview --------------------------------+
|                                                                             |
|   git commit --amend -m "New commit message"                               |
|                                                                             |
|   Rewrites the latest commit with a new message.                           |
|   The commit hash will change.                                              |
|                                                                             |
|   Warning: If this commit has already been pushed, remote history           |
|   must also be updated.                                                     |
|                                                                             |
|   Risk: MEDIUM                                                              |
+-----------------------------------------------------------------------------+

Run this command? [y/N]
```

### Risk Classification

| Risk Level | Examples | Behavior |
|-----------|----------|----------|
| **LOW** | `git status`, `git log`, `git diff` | Auto-executes, no confirmation |
| **MEDIUM** | `git commit`, `git add`, `git push` | Shows preview, requires confirmation |
| **HIGH** | `git push --force`, `git reset --hard`, `git branch -D` | Warning banner, explicit confirmation |

### Smart Warnings

GitMate detects context and warns you:

- **Protected branches**: "This is a protected branch" for `main`, `master`, `develop`
- **Unpushed commits**: "There are 3 unpushed commits" before operations
- **Active operations**: "A merge is in progress" when relevant
- **Safer alternatives**: Suggests `push --force-with-lease` over `push --force`

---

## Installation

### From PyPI (recommended)

```bash
pip install gitmate
# or
pipx install gitmate
```

### From source

```bash
git clone https://github.com/JohnEdwinR/gitmate.git
cd gitmate
python -m venv .venv
.venv\Scripts\Activate.ps1    # Windows PowerShell
# source .venv/bin/activate   # macOS/Linux
pip install -e ".[dev]"
```

---

## Quick Start

```bash
# Interactive mode — guided menus
gitmate

# Show repository status
gitmate status

# Stage all + commit
gitmate save

# Undo last commit (keep changes)
gitmate undo

# Branch operations
gitmate branch create feature/login
gitmate branch switch main

# Sync with remote
gitmate sync push
gitmate sync pull

# Explain a Git command
gitmate explain "git reset --soft HEAD~1"
```

---

## Commands Reference

| Command | Description | Example |
|---------|-------------|---------|
| `gitmate` | Interactive guided mode | `gitmate` |
| `gitmate status` | Show repository state | `gitmate status` |
| `gitmate save` | Stage all + create commit | `gitmate save` |
| `gitmate undo` | Undo menu (keep/discard changes) | `gitmate undo` |
| `gitmate commit` | Commit management menu | `gitmate commit amend-message` |
| `gitmate branch` | Branch operations menu | `gitmate branch create dev` |
| `gitmate sync` | Remote sync menu | `gitmate sync push` |
| `gitmate history` | View recent commits | `gitmate history` |
| `gitmate stash` | Stash management menu | `gitmate stash save` |
| `gitmate explain` | Explain a Git command | `gitmate explain "git rebase"` |
| `gitmate ask` | Natural language (coming soon) | `gitmate ask "undo last commit"` |

---

## Workflows

GitMate includes **20 built-in workflows** across 7 categories:

### Save Changes
| Workflow | Risk | Command |
|----------|------|---------|
| Stage selected files | MEDIUM | `git add <files>` |
| Stage all changes | MEDIUM | `git add -A` |

### Commit Management
| Workflow | Risk | Command |
|----------|------|---------|
| Create a commit | MEDIUM | `git commit -m <message>` |
| Change the latest commit message | MEDIUM | `git commit --amend -m <message>` |
| Add files to the latest commit | MEDIUM | `git commit --amend --no-edit` |
| Initialize a repository | LOW | `git init` |

### Undo Changes
| Workflow | Risk | Command |
|----------|------|---------|
| Undo latest commit (keep changes) | MEDIUM | `git reset --soft HEAD~1` |
| Undo latest commit (unstage) | MEDIUM | `git reset HEAD~1` |
| Discard changes in one file | HIGH | `git checkout -- <file>` |

### Branch Management
| Workflow | Risk | Command |
|----------|------|---------|
| Create a branch | MEDIUM | `git branch <name>` |
| Switch branches | MEDIUM | `git switch <name>` |
| Delete a local branch | HIGH | `git branch -d <name>` |

### Remote Synchronization
| Workflow | Risk | Command |
|----------|------|---------|
| Push a branch | MEDIUM | `git push` |
| Pull remote changes | MEDIUM | `git pull` |
| Set upstream branch | MEDIUM | `git push --set-upstream origin <branch>` |

### Stash Management
| Workflow | Risk | Command |
|----------|------|---------|
| Stash changes | MEDIUM | `git stash push` |
| Restore stashed changes | MEDIUM | `git stash pop` |

### Repository Information
| Workflow | Risk | Command |
|----------|------|---------|
| Show repository status | LOW | `git status` |
| View recent commit history | LOW | `git log --oneline -10` |
| Explain a Git command | LOW | *(explanation only)* |

---

## Architecture

```
CLI Interface (Typer)
       |
  Repository Inspector (subprocess)
       |
  Intent / Workflow Selector
       |
  Workflow Validator (state checks)
       |
  Safety Engine (risk classification)
       |
  Command Builder (template filling)
       |
  Command Preview (Rich panels)
       |
  User Confirmation (questionary)
       |
  Git Executor (subprocess)
       |
  Result Formatter (Rich output)
```

### Project Structure

```
gitmate/
├── gitmate/
│   ├── main.py                 # CLI entry point
│   ├── cli/
│   │   ├── commands.py         # Subcommand implementations
│   │   ├── menus.py            # Interactive menu system
│   │   └── prompts.py          # Questionary wrappers
│   ├── git/
│   │   ├── inspector.py        # Repository state detection
│   │   ├── executor.py         # Command execution + confirmation
│   │   └── commands.py         # Command building + validation
│   ├── workflows/
│   │   ├── registry.py         # Workflow data model + registry
│   │   ├── commits.py          # Commit workflows
│   │   ├── branches.py         # Branch workflows
│   │   ├── remotes.py          # Remote workflows
│   │   ├── undo.py             # Undo workflows
│   │   ├── stash.py            # Stash workflows
│   │   └── status.py           # Status workflows
│   ├── safety/
│   │   ├── rules.py            # Risk levels + protected branches
│   │   ├── classifier.py       # Command risk classification
│   │   └── warnings.py         # Context-aware warnings
│   ├── ui/
│   │   ├── console.py          # Rich console utilities
│   │   ├── panels.py           # Repository summary display
│   │   └── tables.py           # Command preview display
│   └── core/
│       └── models.py           # RepositoryState dataclass
├── tests/
│   ├── conftest.py             # Test fixtures (temp repos)
│   ├── test_inspector.py       # Inspector tests
│   ├── test_workflows.py       # Workflow + registry tests
│   ├── test_safety.py          # Safety engine tests
│   └── test_commands.py        # Command builder tests
├── pyproject.toml              # Build config + metadata
├── LICENSE                     # MIT License
└── README.md
```

---

## Safety Model

GitMate classifies every Git command by risk level and adapts its behavior:

| Level | Criteria | Behavior |
|-------|----------|----------|
| **LOW** | Read-only operations (`status`, `log`, `diff`, `branch`) | Auto-executes |
| **MEDIUM** | State-modifying but recoverable (`add`, `commit`, `push`, `pull`) | Preview + confirmation |
| **HIGH** | Destructive or history-rewriting (`push --force`, `reset --hard`, `branch -D`) | Warning + explicit confirmation |

### Protected Branches

Commands targeting `main`, `master`, or `develop` trigger additional warnings.

### Safer Alternatives

GitMate recommends safer options when available:

| Instead of | GitMate suggests |
|-----------|-----------------|
| `git push --force` | `git push --force-with-lease` |
| `git branch -D` | `git branch -d` (if merged) |
| `git reset --hard` | `git reset --soft HEAD~1` |

---

## Testing

All tests run against temporary Git repositories — never your real repo.

```bash
pytest
```

```
tests/test_commands.py     10 passed
tests/test_inspector.py    18 passed
tests/test_safety.py       22 passed
tests/test_workflows.py    22 passed
                          -------
                    72 passed in 13s
```

---

## Tech Stack

| Component | Library | Purpose |
|-----------|---------|---------|
| CLI Framework | [Typer](https://typer.tiangolo.com/) | Command-line interface |
| Terminal UI | [Rich](https://rich.readthedocs.io/) | Formatted output, panels, syntax highlighting |
| Interactive Prompts | [Questionary](https://questionary.readthedocs.io/) | Menus, text input, confirmations |
| Testing | [Pytest](https://docs.pytest.org/) | Test framework |
| Git Operations | `subprocess` | Running Git commands |

---

## Contributing

Contributions are welcome. Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes
4. Push to the branch (`git push origin feature/my-feature`)
5. Open a Pull Request

Run tests before submitting:

```bash
pytest
```

---

## License

This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.

---

## Author

**John Rajaratnam**
- GitHub: [github.com/JohnEdwinR](https://github.com/JohnEdwinR)
- Project: [github.com/JohnEdwinR/gitmate](https://github.com/JohnEdwinR/gitmate)

---

<div align="center">

**Built with care to make Git less scary.**

</div>
