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.
- 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 --porcelainoutput 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/...) ifghis 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).
+-------------------------------+
| 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 |
+-------------------------------+
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"anderrors="replace", preventing terminal locale encoding crashes on non-ASCII paths.
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\x00bytes. 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.
- Detached HEAD Detection:
is_detached_head()executesgit symbolic-ref -q HEAD. A non-zero return code indicates detached HEAD state. - Default Branch Detection:
get_default_branch()resolves default branch targets by checkingrefs/remotes/origin/HEAD, parsinggit 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 matchorigin, and pops the stash onto the new feature branch.
When --rollback (-r) is invoked:
- Executes
git fetch originto 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>.
# Core CLI (Zero external dependencies)
pip install auto-git-cli
# With TUI support
pip install auto-git-cli[tui]Warning
TUI Status (Beta / Under Development): The Terminal User Interface (auto-git-tui or auto-git --tui) is currently under active development and is considered experimental. It may contain bugs or visual glitches on certain terminals. The core CLI (auto-git) is stable and recommended for routine usage.
git clone https://github.com/Himanshu001-cpu/auto-git.git
cd auto-git
pip install -e .
# Or with TUI support:
pip install -e ".[tui]"After installation, auto-git and auto-git-tui are available globally in your PATH.
python -m auto_git [options]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. |
Stages all changes, displays status summary, prompts for commit message, and pushes to remote:
auto-gitStages changes, auto-generates timestamped commit message, and pushes without interactive prompts:
auto-git -yauto-git -b feature/auth-system -m "feat: implement OAuth login"Preview actions without changing repository state:
auto-git --dry-runInteractively inspect local and remote commit history, then execute a reset:
auto-git -rLaunch the old-school keyboard-driven TUI:
auto-git --tui
# or directly via dedicated command:
auto-git-tui- Navigation:
↑/↓orj/k - Select / Execute:
Enter - Back / Cancel:
Esc/q
Install development dependencies and run pytest:
pip install -r requirements-dev.txt
pytestruff check .
black --check .- 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