---

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)

pip install gitmate
# or
pipx install gitmate

From source

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

# 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.

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	Command-line interface
Terminal UI	Rich	Formatted output, panels, syntax highlighting
Interactive Prompts	Questionary	Menus, text input, confirmations
Testing	Pytest	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:

pytest

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Author

John Rajaratnam

• GitHub: github.com/JohnEdwinR
• Project: github.com/JohnEdwinR/gitmate

---