aarushlohit-git

AARU CLI

A Clean & Powerful Git Workflow Engine

Created by aarushlohit · github.com/aarushlohit · Zairok App

AARU wraps Git with a clean, opinionated command surface. Every destructive or side-effect action requires an explicit confirmation flag — you always see what will happen before it happens.

🎉 What's New in v2.0

• One-command install: pip install aarushlohit-git — works on all platforms
• Zero PATH hassles: python3 -m aarush works immediately after install (no terminal restart)
• Easy installers: One-line bash/PowerShell scripts with auto PATH setup for Linux/macOS/Windows
• Rich terminal UI: Colored output with ✔/✖/ℹ icons for better readability
• Complete command suite: 23 commands covering all Git workflows — init, save, sync, fork-sync, checkout-pr, and more
• Safety-first design: Destructive commands require explicit --confirm or --yes flags
• Professional banner: aaru aaru shows system info, repo status, and quick start guide

---

Table of Contents

• Installation
• Quick Start
• Command Reference
  • Info & Setup
  • Repository
  • Workflow
  • Branch
  • Remote
  • Stash
  • Raw Passthrough
• Safety Model
• Real-World Workflows

---

Installation

Option 1 — pip (recommended, all platforms)

pip install aarushlohit-git

After install, if aaru isn't recognised yet (PATH not updated), use this fallback immediately:

python3 -m aarush --help   # Linux / macOS
python  -m aarush --help   # Windows

Open a new terminal and aaru will work everywhere.

---

Option 2 — Easy installer scripts

Linux / macOS — one-liner

# From the repo:
bash install.sh

# Or directly from GitHub (no clone needed):
curl -fsSL https://raw.githubusercontent.com/aarushlohit/GIT_PROTOCOL/main/install.sh | bash

• Auto-detects pipx → falls back to pip --user
• Handles externally-managed Python (Arch, Debian 12+, Ubuntu 23+)
• Automatically adds ~/.local/bin to your shell config

Windows — double-click installer

install_windows.bat

• Double-click it in Explorer or run it in Command Prompt
• Auto-detects Python, downloads Python installer if missing
• Permanently adds the Scripts folder to your user PATH (no admin required)

Windows — PowerShell one-liner

# Run in PowerShell:
iwr https://raw.githubusercontent.com/aarushlohit/GIT_PROTOCOL/main/install.ps1 | iex

---

Option 3 — Standalone binary (no Python required)

# Linux / macOS:
./build_exe.sh
sudo cp dist/aaru /usr/local/bin/

# Windows:
build_exe.bat
# Then copy dist\aaru.exe to a folder in your PATH

---

Upgrading

pip install --upgrade aarushlohit-git

---

Quick Start

# 1. Initialize a new repo
aaru init

# 2. Set your Git identity (one-time)
aaru config-user --name "Your Name" --email "you@example.com"

# 3. Do some work, then save it
aaru save "add login page"

# 4. Push to remote
aaru send --yes

# 5. Pull + push in one step
aaru sync

---

Command Reference

Info & Setup

---

aaru aaru

Display the ASCII art banner with system info (Git version, Python version, repo, remote URL).

aaru aaru

---

aaru config-user

Configure your Git user name and email globally. Interactive prompts if flags are omitted.

aaru config-user --name "Jane Doe" --email "jane@example.com"
aaru config-user        # prompts for both

---

Repository

---

aaru init

Initialize a new Git repository in the current directory and create a .aaru workspace folder.

aaru init

---

aaru clone <repo-url>

Clone a remote repository and set up the .aaru directory automatically.

aaru clone https://github.com/user/repo.git

---

aaru config

Print the current Git configuration (equivalent to git config --list).

aaru config

---

Workflow

---

aaru status

Show the working-tree status — modified files, staged files, untracked files.

aaru status

---

aaru save <message>

Stage all changed files and commit in one step.
Equivalent to: git add -A && git commit -m "<message>"

aaru save "fix navbar alignment"
aaru save "initial commit"

---

aaru history

Show a compact, decorated commit graph with branch pointers.

aaru history

---

aaru diff

Show unstaged changes in the working tree.

aaru diff

---

aaru undo

Soft-undo the last commit. Keeps all your changes in the working tree (nothing is lost).
Equivalent to: git reset HEAD~1

Without --confirm: shows which commit would be undone — does NOT undo yet.
With --confirm: actually runs the undo.

aaru undo              # preview: "Would undo: abc1234 fix navbar"
aaru undo --confirm    # actually undoes the commit

---

Branch

---

aaru create <branch>

Create a new branch. By default you stay on your current branch — the new branch is created but not switched to.

aaru create feature/login          # creates branch, stays where you are
aaru create feature/login --switch # creates AND switches to it

---

aaru switch <branch>

Switch to an existing branch.

aaru switch main
aaru switch feature/login

---

aaru delete <branch>

Delete a branch. Safe by default — refuses if the branch has unmerged commits.
Requires --confirm to actually execute.

aaru delete old-branch                      # blocked: shows error with instructions
aaru delete old-branch --confirm            # safe delete (refuses if unmerged)
aaru delete old-branch --force --confirm    # force-delete even if unmerged

---

aaru branches

List all local and remote branches.

aaru branches

---

Remote

---

aaru send

Push the current branch to its remote tracking branch.

Without --yes: shows a preview of commits that would be pushed — does NOT push.
With --yes: actually pushes.

aaru send          # preview: shows commits to be pushed
aaru send --yes    # push confirmed

---

aaru update

Fetch all remotes without merging. Equivalent to git fetch --all.

aaru update

---

aaru sync

Pull remote changes then push local commits in one step.
Equivalent to: git pull && git push

Use --no-push to only pull without pushing.

aaru sync              # pull + push
aaru sync --no-push    # pull only

---

aaru add-upstream <url>

Add the upstream remote for a forked repository (one-time setup before using fork-sync).
Prompts for URL if not provided.

aaru add-upstream https://github.com/original/repo.git
aaru add-upstream    # prompts for URL

---

aaru fork-sync

Sync your fork with the original upstream repository.

Steps performed:

1. Fetch from upstream remote
2. Merge upstream/<current-branch> into your local branch
3. Push the updated branch to origin (your fork)

# One-time setup:
aaru add-upstream https://github.com/original/repo.git

# Then sync any time:
aaru fork-sync              # fetch + merge + push
aaru fork-sync --no-push    # fetch + merge only (don't push)
aaru fork-sync myupstream   # use a different upstream remote name

---

aaru checkout-pr <number>

Fetch a pull request as a local branch for testing.

Without --switch: fetches the PR branch, you stay on your current branch.
With --switch: fetches and switches to the PR branch.

aaru checkout-pr 42                       # fetch PR #42, stay on current branch
aaru checkout-pr 42 --switch              # fetch and switch to pr-42
aaru checkout-pr 42 --remote upstream     # fetch from a different remote

---

Stash

---

aaru stash [label]

Stash all current working-tree changes. Optionally tag the stash with a label.

aaru stash                          # stash with no label
aaru stash "wip: auth refactor"     # stash with a descriptive label

---

aaru stash-pop

Apply the most recent stash and remove it from the stash list.

aaru stash-pop

---

aaru stash-list

List all saved stashes.

aaru stash-list

---

Raw Passthrough

aaru raw -- <git args>

Pass any git command directly through the AARU pipeline. Use -- to separate AARU flags from git flags.

aaru raw -- log --oneline -10
aaru raw -- rebase -i HEAD~3
aaru raw -- remote -v
aaru raw -- cherry-pick abc1234

Note: The -- separator is required whenever your git command includes flags (anything starting with -).

---

Safety Model

AARU follows one rule: commands with side effects are safe by default and require an explicit opt-in flag.

---

Real-World Workflows

Starting a new feature

aaru status                          # check current state
aaru create feature/user-auth        # create branch, stay on current
aaru switch feature/user-auth        # switch to it when ready
# ... write code ...
aaru save "add JWT middleware"
aaru send --yes                      # push to remote

Undoing a bad commit

aaru undo                  # preview: "Would undo: abc1234 oops wrong file"
aaru undo --confirm        # actually undo it
# fix your files
aaru save "correct commit message"

Syncing a fork with upstream

# One-time setup
aaru add-upstream https://github.com/original/project.git

# Every time you want to sync
aaru fork-sync              # fetch upstream + merge + push to your fork
aaru fork-sync --no-push    # only pull from upstream, review before pushing

Testing a pull request locally

aaru checkout-pr 84                  # fetch pr-84, stay on current branch
# review the diff with: aaru diff
aaru checkout-pr 84 --switch         # now switch to it and test
aaru switch main                     # done testing, switch back

Saving work-in-progress before switching context

aaru stash "wip: payment flow"       # stash current work with a label
aaru switch hotfix/login-crash       # switch context
# ... fix the bug ...
aaru save "fix login crash on mobile"
aaru send --yes
aaru switch feature/payment          # come back
aaru stash-pop                       # restore your work

Cleaning up old branches

aaru branches                                    # see all branches
aaru delete old-experiment                       # blocked — shows what to add
aaru delete old-experiment --confirm             # safe delete
aaru delete wip-never-merged --force --confirm   # force delete unmerged branch

---

Getting Help

Every command has built-in help:

aaru --help
aaru <command> --help

# Examples:
aaru send --help
aaru delete --help
aaru fork-sync --help
aaru checkout-pr --help