Metadata-Version: 2.4
Name: auto-git-cli
Version: 1.0.0
Summary: Zero-dependency CLI tool to automate Git add, commit, branch creation, commit rollback, and GitHub PRs.
Author-email: Himanshu <himanshu@example.com>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/Himanshu001-cpu/auto-git
Project-URL: Repository, https://github.com/Himanshu001-cpu/auto-git
Project-URL: Issues, https://github.com/Himanshu001-cpu/auto-git/issues
Project-URL: Changelog, https://github.com/Himanshu001-cpu/auto-git/blob/main/CHANGELOG.md
Keywords: git,automation,cli,python,github,developer-tools
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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 :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# auto-git

[![CI](https://github.com/Himanshu001-cpu/auto-git/actions/workflows/ci.yml/badge.svg)](https://github.com/Himanshu001-cpu/auto-git/actions/workflows/ci.yml)
[![Python Version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://www.python.org/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

A zero-dependency command-line utility written in standard Python to automate routine Git tasks: repository initialization, status checking, staging, committing, branch management, commit rollbacks, and GitHub Pull Request creation.

---

## Technical Overview & Features

* **Repository Initialization**: Detects if the current directory is a Git repository. If not initialized, it can run `git init`, configure default branch names (`main`), and attach GitHub remote URLs.
* **Git Porcelain Parsing**: Parses `git status -z --porcelain` output using NUL delimiters. Safely handles filenames with spaces, Unicode characters, and rename/copy states without shell escaping issues.
* **Merge Conflict Detection**: Identifies unmerged conflict status codes (`UU`, `AA`, `DD`, etc.) and halts commit operations to prevent committing unresolved conflict markers.
* **Branch Management**: Supports switching between existing branches, creating new feature branches, and protecting the default branch (`main`) by offering to redirect uncommitted changes to a new feature branch.
* **Detached HEAD Resolution**: Detects detached HEAD states and prompts for target branch resolution or creates temporary branches automatically when running non-interactively.
* **Interactive Log & Rollback**: Displays local and remote commit history side-by-side and executes soft (`--soft`), mixed (`--mixed`), or hard (`--hard`) resets to chosen target commits.
* **GitHub CLI & Browser PR Integration**: Opens Pull Requests automatically using GitHub CLI (`gh pr create`) when available, or generates and launches a GitHub web browser comparison link (`https://github.com/user/repo/compare/...`) if `gh` is unauthenticated or not installed.
* **Terminal User Interface (TUI)**: Opt-in interactive curses interface (`auto-git --tui`) offering dashboard view, keyboard-driven navigation (`↑`/`↓`/`j`/`k`), stage/commit wizard, branch switcher/creator, commit rollback picker, and pull request builder.
* **Subprocess Security**: All Git commands execute via list arguments without `shell=True`, eliminating shell injection risks.
* **Zero External Dependencies**: Operates strictly using Python standard library modules (`subprocess`, `argparse`, `os`, `sys`, `re`, `datetime`, `urllib`, `webbrowser`, `curses`).

---

## Architecture & Internal Design

```
                     +-------------------------------+
                     |         CLI Invocation        |
                     |       (auto-git / -y)         |
                     +---------------+---------------+
                                     |
                                     v
                     +-------------------------------+
                     |     Repo & State Inspection   |
                     |  git status -z --porcelain    |
                     +---------------+---------------+
                                     |
           +-------------------------+-------------------------+
           |                         |                         |
           v                         v                         v
+--------------------+    +--------------------+    +--------------------+
|  Merge Conflict?   |    |   Detached HEAD?   |    | Default Branch?    |
| Stop and warn user |    | Prompt/auto-create |    | Offer feature      |
| before staging     |    | branch             |    | branch redirect    |
+--------------------+    +--------------------+    +--------------------+
           |                         |                         |
           +-------------------------+-------------------------+
                                     |
                                     v
                     +-------------------------------+
                     |       Stage & Commit          |
                     |   git add -A / git commit     |
                     +---------------+---------------+
                                     |
                                     v
                     +-------------------------------+
                     |          Remote Push          |
                     |     git push origin <head>    |
                     +---------------+---------------+
                                     |
                                     v
                     +-------------------------------+
                     |     Pull Request Creation     |
                     | gh pr create OR browser link  |
                     +-------------------------------+
```

### 1. Subprocess Execution & Security Model
All command executions are routed through `run_command()`, which wraps `subprocess.run()`. 
* **List Arguments**: Commands are passed as lists of strings (e.g., `["git", "commit", "-m", msg]`), bypassing shell invocation (`shell=False`). Arguments containing spaces, quotes, or special characters are passed directly to the executable binary.
* **UTF-8 Character Decoding**: Standard streams output is parsed with `encoding="utf-8"` and `errors="replace"`, preventing terminal locale encoding crashes on non-ASCII paths.

### 2. Machine-Readable Git Status Parsing
Rather than parsing standard line-based `git status` output (which quotes special characters and wraps spaces), `auto_git` uses `git status -z --porcelain`:
* **NUL Delimiters (`\x00`)**: Tokens are split by `\x00` bytes. Filenames containing spaces, quotes, or non-ASCII characters are returned in raw form.
* **Rename/Copy Resolution**: Renamed (`R`) and copied (`C`) status codes are followed by two NUL-terminated strings (the new path and the original source path), which are parsed without path string truncation.

### 3. Branch & State Management
* **Detached HEAD Detection**: `is_detached_head()` executes `git symbolic-ref -q HEAD`. A non-zero return code indicates detached HEAD state.
* **Default Branch Detection**: `get_default_branch()` resolves default branch targets by checking `refs/remotes/origin/HEAD`, parsing `git remote show origin`, and checking local branch existence (`main`, `master`, `develop`).
* **Feature Branch Redirection**: When working on the default branch with uncommitted changes, `move_changes_to_feature_branch()` stashes uncommitted changes, creates a feature branch, resets the local default branch to match `origin`, and pops the stash onto the new feature branch.

### 4. Interactive Rollback Mechanism
When `--rollback` (`-r`) is invoked:
1. Executes `git fetch origin` to update remote references.
2. Formats recent commit history (`git log --oneline -n 15`) for both local HEAD and remote tracking branches.
3. Validates target selection using `git cat-file -t <commit_hash>`.
4. Applies `git reset [--soft | --mixed | --hard] <commit_hash>`.

---

## Installation & Setup

### Option 1: Install via pip (Local Editable Mode)
```bash
git clone https://github.com/Himanshu001-cpu/auto-git.git
cd auto-git
pip install -e .
```
After installation, `auto-git` is available globally in your PATH.

### Option 2: Run directly as a Python module

```bash
python -m auto_git [options]
```

---

## Command Options & Usage

```bash
auto-git [options]
```

| Option | Long Option | Description |
| :--- | :--- | :--- |
| `-h` | `--help` | Show help message and exit. |
| `-v` | `--version` | Show program version and exit. |
| `-b <branch>` | `--branch <branch>` | Switch to or create the specified branch. |
| `-m <msg>` | `--message <msg>` | Use a custom commit message (skips input prompt). |
| `-y` | `--yes` | Non-interactive mode: auto-generate commit message, skip prompts, and push. |
| `-r` | `--rollback` | Display local & remote commit history and perform an interactive reset. |
| `-p` | `--pull-request` | Open a GitHub Pull Request targeting the default branch. |
| | `--tui` | Launch the interactive Terminal User Interface (Linux/macOS). |
| | `--no-push` | Stage and commit changes locally without pushing to remote. |
| | `--dry-run` | Display simulated actions without modifying repository state. |

---

## Examples

### 1. Interactive Run
Stages all changes, displays status summary, prompts for commit message, and pushes to remote:
```bash
auto-git
```

### 2. Automated Script / CI Run (--yes)
Stages changes, auto-generates timestamped commit message, and pushes without interactive prompts:
```bash
auto-git -y
```

### 3. Switch/Create Branch & Commit
```bash
auto-git -b feature/auth-system -m "feat: implement OAuth login"
```

### 4. Dry Run Simulation
Preview actions without changing repository state:
```bash
auto-git --dry-run
```

### 5. Rollback Commits
Interactively inspect local and remote commit history, then execute a reset:
```bash
auto-git -r
```

### 6. Interactive Terminal User Interface (TUI Mode)
Launch the old-school keyboard-driven TUI:
```bash
auto-git --tui
```
* **Navigation**: `↑` / `↓` or `j` / `k`
* **Select / Execute**: `Enter`
* **Back / Cancel**: `Esc` / `q`

---

## Development & Testing

### Running Tests
Install development dependencies and run `pytest`:
```bash
pip install -r requirements-dev.txt
pytest
```

### Code Formatting & Linting
```bash
ruff check .
black --check .
```

---

## Project Metadata & GitHub Configuration

* **Project Description**: Zero-dependency CLI tool to automate Git add, commit, branch creation, commit rollback, and GitHub PRs.
* **Topics**: `git`, `automation`, `cli`, `python`, `github`, `developer-tools`
* **License**: GPLv3
