auto-git

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:

Executes git fetch origin to update remote references.
Formats recent commit history (git log --oneline -n 15) for both local HEAD and remote tracking branches.
Validates target selection using git cat-file -t <commit_hash>.
Applies git reset [--soft | --mixed | --hard] <commit_hash>.

Installation & Setup

Option 1: Install via pip (Local Editable Mode)

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

python -m auto_git [options]

Command Options & Usage

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:

auto-git

2. Automated Script / CI Run (--yes)

Stages changes, auto-generates timestamped commit message, and pushes without interactive prompts:

auto-git -y

3. Switch/Create Branch & Commit

auto-git -b feature/auth-system -m "feat: implement OAuth login"

4. Dry Run Simulation

Preview actions without changing repository state:

auto-git --dry-run

5. Rollback Commits

Interactively inspect local and remote commit history, then execute a reset:

auto-git -r

6. Interactive Terminal User Interface (TUI Mode)

Launch the old-school keyboard-driven TUI:

auto-git --tui

Navigation: ↑ / ↓ or j / k
Select / Execute: Enter
Back / Cancel: Esc / q

Development & Testing

Running Tests

Install development dependencies and run pytest:

pip install -r requirements-dev.txt
pytest

Code Formatting & Linting

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

auto_git_cli-1.0.0.tar.gz (45.8 kB view details)

Uploaded Jul 25, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

auto_git_cli-1.0.0-py3-none-any.whl (49.1 kB view details)

Uploaded Jul 25, 2026 Python 3

File details

Details for the file auto_git_cli-1.0.0.tar.gz.

File metadata

Download URL: auto_git_cli-1.0.0.tar.gz
Upload date: Jul 25, 2026
Size: 45.8 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.4

File hashes

Hashes for auto_git_cli-1.0.0.tar.gz
Algorithm	Hash digest
SHA256	`166e4efdde96d5184c3d1d175e74c52466bb4233fa5528868bea0edbfb62b402`
MD5	`b3ecb3547f260e340810d664d5351912`
BLAKE2b-256	`46b38dd70d8b19741b49c5569e55cc5b2c1f7fbe7c23d416bbd5500cc3c0ca68`

See more details on using hashes here.

File details

Details for the file auto_git_cli-1.0.0-py3-none-any.whl.

File metadata

Download URL: auto_git_cli-1.0.0-py3-none-any.whl
Upload date: Jul 25, 2026
Size: 49.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.14.4

File hashes

Hashes for auto_git_cli-1.0.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`c143bb4c6852eec0fcf471595330d281c190a65c71b81006dda287e4a72a4aec`
MD5	`d445d0ec42416e7438346341121eab8f`
BLAKE2b-256	`dc028ed7b46e227c46c5a1a2dcdb871247ae3dd5290e9a9d273415a2fa98a316`

See more details on using hashes here.

Release history Release notifications | RSS feed

1.0.1

Jul 25, 2026

This release

1.0.0

Jul 25, 2026

auto-git-cli 1.0.0

auto-git

Technical Overview & Features

Architecture & Internal Design

1. Subprocess Execution & Security Model

2. Machine-Readable Git Status Parsing

3. Branch & State Management

4. Interactive Rollback Mechanism

Installation & Setup

Option 1: Install via pip (Local Editable Mode)

Option 2: Run directly as a Python module

Command Options & Usage

Examples

1. Interactive Run

2. Automated Script / CI Run (--yes)

3. Switch/Create Branch & Commit

4. Dry Run Simulation

5. Rollback Commits

6. Interactive Terminal User Interface (TUI Mode)

Development & Testing

Running Tests

Code Formatting & Linting

Project Metadata & GitHub Configuration

Project links

Key dates

1 maintainer

Credits

License

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

Release history Release notifications | RSS feed