git-uncommitted-scanner 0.1.3__tar.gz → 0.2.0__tar.gz

git_uncommitted_scanner-0.2.0/AGENTS.md

@@ -0,0 +1,85 @@
+# 🤖 AGENTS.md – Project Guidelines & Rules for Autonomous AI Agents
+
+Welcome to **git-uncommitted-scanner**. This document defines the mandatory guidelines, architectural standards, quality controls, and PR rules that **all AI agents** (including GitScanner Bolt ⚡, GitScanner Evo 🚀, GitScanner Palette 🎨, and standard coding assistants) MUST follow when contributing to this codebase.
+
+---
+
+## 1. Project Overview & Technology Stack
+
+**`git-uncommitted-scanner`** is a high-speed, cross-platform CLI & TUI utility that scans directories recursively to detect Git repositories with pending uncommitted changes.
+
+- **Primary Language**: Python >= 3.9
+- **CLI Engine**: `Typer`
+- **Console Output & Styling**: `Rich`
+- **Interactive TUI**: `Textual`
+- **Subprocess & OS Logic**: Standard library `subprocess`, `pathlib.Path`
+- **Build Backend**: `setuptools` (PEP 621, pinned `<75.0` in `pyproject.toml`)
+
+---
+
+## 2. Core Code Standards
+
+1. **Strict Single Entry Point**: All application logic, CLI routing, and TUI widgets MUST reside strictly under `git_scanner/main.py`. AI agents **MUST NOT** split the codebase into separate sub-modules (e.g., `git_scanner/tui.py`, `utils.py`, `core.py`) or introduce circular cross-file imports under the pretext of "lazy loading" or "modularization".
+2. **Cross-Platform Compatibility**: Every file operation and terminal invocation must work seamlessly across Windows, macOS, and Linux.
+3. **No Unnecessary Dependencies**: Prefer standard library solutions or existing dependencies (`typer`, `rich`, `textual`). Do not add external packages without explicit approval.
+4. **Zero Regressions & Feature Preservation**: Never delete, degrade, or revert existing features (e.g., CSV & JSON export formats, DataTable auto-focus, keybindings, configuration file loaders, CLI options) during optimization or refactoring passes. Agents **MUST** pull and branch strictly from the latest `origin/Dev2Auto` HEAD to prevent rolling back recent features.
+
+---
+
+## 3. Strict "No Fake Progress" Policy
+
+- **Zero-Change Execution**: If an agent run uncovers no practical, high-value performance, feature, or UX improvement, the agent **MUST NOT** modify any files or submit commits/PRs.
+- **No Pure Aesthetic Churn**: Never refactor code simply to change formatting, variable names, line spacing, or syntax style unless it delivers measurable, practical utility.
+- **No Harmful Micro-Optimizations**: Never fragment the codebase or sacrifice architectural integrity for negligible micro-benchmarks (such as moving classes into separate files to shave 20ms import latency). If lazy loading is ever appropriate, perform it locally within the relevant function inside `git_scanner/main.py`.
+- **Empirical Verification**: All changes must be verified locally by running `scanrepos` or test commands.
+
+---
+
+## 4. Performance Guidelines (GitScanner Bolt ⚡)
+
+- Keep imports clean within `git_scanner/main.py` without violating the single entry point rule.
+- Keep directory walking efficient (`Path.rglob` or `os.scandir`) and minimize `git status` subprocess execution overhead.
+- Ensure `Textual` worker threads run heavy directory scans in the background without blocking the UI main thread.
+
+---
+
+## 5. Feature & Product Evolution Guidelines (GitScanner Evo 🚀)
+
+- Focus on practical, working CLI and TUI enhancements (e.g. branch info, uncommitted file counts, exclusion filters, JSON export, config files).
+- No stub implementations, fake UI elements, TODO placeholders, or broken workflows.
+
+---
+
+## 6. UX & Design Guidelines (GitScanner Palette 🎨)
+
+- Maintain high visual contrast and modern terminal styling using `Rich` tables and `Textual` components.
+- Ensure keyboard shortcuts are clean, intuitive, and properly documented in the TUI footer.
+- Provide clear error feedback if external terminal execution fails.
+
+---
+
+## 7. Artifact & Cleanup Rules
+
+- Never commit build artifacts (`dist/`, `build/`, `*.egg-info/`, `__pycache__/`).
+- Never commit scratch files, `.patch`, `.log`, or `.tmp` files.
+- Keep `.gitscanner/` logs focused on long-term learnings.
+
+---
+
+# 8. PR & Code Generation Rules
+
+When creating a Pull Request or submitting code changes, you MUST structure the PR description with the following sections:
+
+1. **Executive Summary**: 2-3 sentences max explaining WHAT was changed and WHY.
+
+2. **Impact & Safety Matrix**:
+
+| File Changed / Removed | Action | Technical Reason | Post-Removal/Update Impact | Risk Level |
+| :--- | :--- | :--- | :--- | :--- |
+| `path/to/file` | Modified/Deleted | Why it was changed | What improves or changes | 🟢 Low / 🟡 Med / 🔴 High |
+
+3. **Verification**: State tests run or how you verified this won't break existing IPC/UI threads.
+
+4. **Clean Artifacts**: NEVER commit `.patch`, `.log`, or `.tmp` files.
+
+5. **Update documentations**: always update any Documentation, when ever new feature is added or any functionality changes.

git_uncommitted_scanner-0.2.0/CHANGELOG.md

@@ -0,0 +1,115 @@
+# 📜 Changelog
+
+All notable changes to the `git-uncommitted-scanner` project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-09-19
+
+> **Major Milestone Release**: Aggregating all architectural overhauls, high-speed concurrency engines, interactive TUI enhancements, and script automation workflows developed in the `Dev2Auto` pipeline since `v0.1.3`.
+
+### 🚀 Added
+- **Script Automation & Quiet Mode (`--quiet` / `-q`)**: Added `--quiet` flag to suppress all Rich headers, animated spinners, and formatted tables, outputting only raw, newline-delimited repository paths for clean piping into tools like `xargs`.
+- **Untracked File Exclusion (`--exclude-untracked` / `-u`)**: Added filtering option to ignore repositories with only untracked files (`modified == 0 and untracked > 0`), reducing noise from temporary scratch files.
+- **Direct Module Execution (`python -m git_scanner`)**: Added `git_scanner/__main__.py` to allow running the utility even if Python's user Scripts directory is not configured on the system `PATH`.
+- **Version Query Flag (`--version` / `-v`)**: Added fast `--version` display to check the installed release without running scans.
+- **Upstream Synchronization Metrics**: Branch status now displays ahead/behind commit indicators (`[↑X ↓Y]`) by parsing `git status --porcelain -b`.
+- **Dual Export Capabilities**: Dynamic export supporting both JSON (`.json`) and CSV (`.csv`) output formats via `--export <path>`.
+- **Last Commit Age Metric**: Added relative last commit timestamp (`git log -1 --format=%cr`) to CLI output, interactive TUI table, and structured exports.
+- **Persistent Configuration Support**: Automatic configuration parsing from `~/.gitscannerrc`, `.gitscannerrc`, and `pyproject.toml` (`[tool.gitscanner]`) to define default `exclude` directories and `max_depth`.
+- **Path & Depth Filters**: Added `--max-depth` (`-d`) recursion constraints and `--exclude` (`-e`) directory blacklisting across both CLI and TUI modes.
+- **Git Submodule Detection**: Detects `.git` files (submodules/worktrees) alongside `.git` directories.
+
+### ⚡ Changed & Performance
+- **Generative Traversal Pipelining**: Removed blocking `list()` wrapping from `find_git_repos` calls in both CLI and TUI modes, allowing worker threads to begin checking repository git status concurrently while disk traversal is in progress.
+- **Parallel Subprocess Execution**: Integrated `ThreadPoolExecutor` (up to 32 concurrent workers) in both CLI and TUI worker threads, delivering 2x–4x scan speedups on multi-repository projects.
+- **Batched TUI Updates**: Wrapped row additions inside `table.batch_update()` within `_render_table_rows`, preventing per-row UI reflows and eliminating UI stutter on large workspaces.
+- **`os.scandir` Traversal Engine**: Replaced `os.walk` with iterative DFS using `os.scandir`, cutting directory scanning latency by ~41% and pruning heavy directories (`node_modules`, `.venv`, `build`, `dist`, `.tox`, etc.) without entering `.git` directories.
+- **Unified Status Parsing**: Merged branch name, upstream sync, modified count, and untracked count retrieval into a single `git status --porcelain -b` call, cutting git execution overhead in half.
+
+### 🎨 User Experience
+- **Interactive Column Sorting**: Click any column header (ID, Path, Branch, Modified, Untracked, Last Commit) in the TUI to toggle ascending (▲) and descending (▼) sort order with instant feedback.
+- **Chronological Timestamp Sorting**: Refactored Last Commit sorting in the TUI to sort by exact Unix epoch timestamps instead of string comparison, accurately ordering minutes vs weeks.
+- **Live Search & Filter Overlay**: Press <kbd>/</kbd> or <kbd>s</kbd> to toggle real-time repository filtering by path or branch name; press <kbd>Escape</kbd> to close and return focus to the table.
+- **Auto-Focus on Load**: DataTable automatically gains focus upon scan completion for instant keyboard arrow-key navigation.
+- **OS-Aware Terminal Launcher**: Extended `open_external_terminal()` with detection for Windows Terminal (`wt`), PowerShell 7 (`pwsh`), macOS `iTerm2`, and modern Linux terminals (`alacritty`, `kitty`, `konsole`, `xfce4-terminal`, etc.).
+- **Dynamic Path Truncation**: Responsive path truncation ensures full repository paths adapt to terminal screen dimensions without clipping UI columns.
+
+### 🐛 Fixed & Reliability
+- **Windows Codepage & Encoding Crash Prevention**: Reconfigured UTF-8 output streams to prevent legacy Windows `cmd.exe` codepage encoding crashes.
+- **Export Separation**: Decoupled `display_branch` (with `[↑X ↓Y]` ANSI formatting) from `branch` (raw string), ensuring clean JSON and CSV exports.
+- **Worker Cancellation Safety**: Background directory scanning in `GitScannerTUI` checks `worker.is_cancelled` at every yield step to allow clean and instant cancellation.
+
+### 📚 Documentation
+- **Comprehensive Installation & Troubleshooting Guide**: Added step-by-step guides for `pipx`, `uv`, and `pip`, including 1-line PowerShell and bash commands to resolve missing PATH / command not found errors on Windows, macOS, and Linux.
+
+---
+
+## [0.1.6] - 2026-08-18
+
+### 🚀 Features (Evo 🚀)
+- **Last Commit Age Metric**: Added relative last commit timestamp (`git log -1 --format=%cr`) to CLI output, interactive TUI table, and JSON export to help developers instantly prioritize stale vs recently touched dirty repos.
+- **Enhanced Terminal Launcher**: Extended `open_external_terminal()` with `shutil.which` detection supporting Windows Terminal (`wt`), PowerShell 7 (`pwsh`), macOS `iTerm2`, and modern Linux terminals (`alacritty`, `kitty`, `konsole`, `xfce4-terminal`, etc.).
+
+### 🎨 User Experience (Palette 🎨)
+- **Search Escape & Keybinding Ergonomics**: Added <kbd>Escape</kbd> key handler to instantly cancel/dismiss search and return table focus. Supported both <kbd>/</kbd> and <kbd>s</kbd> search shortcuts.
+- **Chronological Timestamp Sorting**: Refactored Last Commit sorting in the TUI to sort by exact Unix epoch timestamps instead of string comparison, ensuring proper chronological order (e.g. distinguishing minutes from weeks accurately).
+
+---
+
+## [0.1.5] - 2026-08-15
+
+### ⚡ Performance (Bolt ⚡)
+- **Parallel Git Status Execution**: Integrated `ThreadPoolExecutor` in both CLI and TUI worker threads, executing `git status` subprocesses in parallel (2x–4x scan speedup on multi-repository projects).
+
+### 🚀 Features (Evo 🚀)
+- **Configuration File Support**: Added automatic configuration parsing from `~/.gitscannerrc`, `.gitscannerrc`, and `pyproject.toml` (`[tool.gitscanner]`) to define default `exclude` folders and `max_depth`.
+
+### 🎨 User Experience (Palette 🎨)
+- **Interactive Column Sorting**: Implemented `@on(DataTable.HeaderSelected)` to allow clicking any column header (ID, Path, Branch, Modified, Untracked) in the TUI to toggle ascending (▲) and descending (▼) sort order with instant feedback.
+
+---
+
+## [0.1.4] - 2026-08-12
+
+### ⚡ Performance (Bolt ⚡)
+- **Single Subprocess Status Parsing**: Refactored status check to use `git status --porcelain -b`. Retrieves branch name, modified file count, and untracked file count in a single subprocess call, cutting git execution overhead by 50%.
+- **`os.scandir` Traversal Pruning**: High-speed directory scanner automatically skips heavy folders (`node_modules`, `.venv`, `build`, `dist`, `.tox`, etc.) without entering `.git` directories.
+
+### 🚀 Features (Evo 🚀)
+- **Advanced Path Filtering**: Added `--max-depth` (`-d`) to limit search depth and `--exclude` (`-e`) for custom folder exclusions across CLI and TUI modes.
+- **Git Submodule Support**: Added detection for `.git` files (submodules) alongside `.git` directories.
+- **JSON Data Export**: Added `--export <path.json>` flag to save scan results to structured JSON format.
+
+### 🎨 User Experience (Palette 🎨)
+- **TUI Ergonomics**: Added <kbd>Enter</kbd> key and double-click row selection (`@on(DataTable.RowSelected)`) to launch native terminals directly from the TUI.
+- **Visual Feedback**: Added non-intrusive toast notifications when spawning terminals and automatic path truncation for long workspace directories.
+- **Cross-Platform Fixes**: Reconfigured UTF-8 console output to prevent legacy Windows `cmd.exe` codepage encoding crashes.
+
+---
+
+## [0.1.3] - 2026-08-07
+
+### 🚀 Added
+- **AI Agent Operating Rules & Guidelines**: Created [`AGENTS.md`](AGENTS.md) defining strict contribution standards, performance policies, empirical verification rules, and mandatory PR structures (Executive Summary, Impact & Safety Matrix, Verification).
+- **Scheduled Agent Prompt Suite**: Tailored three dedicated autonomous agent personas for the project:
+  - ⚡ **GitScanner Bolt**: Performance, directory scan, and thread optimizer ([`prompt-bolt.md`](prompt-bolt.md)).
+  - 🚀 **GitScanner Evo**: Feature evolution, CLI options, and cross-platform capability engineer ([`prompt-evo.md`](prompt-evo.md)).
+  - 🎨 **GitScanner Palette**: Textual TUI & CLI UX evolution engineer ([`prompt-pallete.md`](prompt-pallete.md)).
+- **Automated PR Review Integration**: Created [`.coderabbit.yaml`](.coderabbit.yaml) for assertive CodeRabbit AI code reviews.
+- **Dedicated Agent Branching**: Established the `Dev2Auto` branch as the target branch for automated agent PRs and feature submissions.
+
+### ⚡ Changed
+- **Packaging & CI/CD Docs**: Updated package setup references and GitHub Actions PyPI deployment documentation for automated OIDC publishing on GitHub releases.
+
+---
+
+## [0.1.0] - Initial Release
+
+### 🚀 Added
+- Asynchronous deep directory scanner using Python standard `subprocess` and `pathlib.Path`.
+- Standard CLI table output powered by `Typer` and `Rich`.
+- Interactive Neon-Cyan Terminal User Interface (TUI) powered by `Textual`.
+- Cross-platform native terminal spawning (`cmd`, `osascript`, `gnome-terminal`, `konsole`, `alacritty`, `xterm`).
+- Registered global CLI command `scanrepos`.

{git_uncommitted_scanner-0.1.3 → git_uncommitted_scanner-0.2.0}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) [year] [fullname]
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

git_uncommitted_scanner-0.2.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include readme.md
+include CHANGELOG.md
+include AGENTS.md
+include pyproject.toml
+prune docs
+prune .gitscanner
+global-exclude *.py[cod] __pycache__ *.so *.dylib

git_uncommitted_scanner-0.2.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.1
+Name: git-uncommitted-scanner
+Version: 0.2.0
+Summary: A lightweight CLI to scan for uncommitted Git repositories.
+License: MIT
+Project-URL: Homepage, https://github.com/RootDeveloperDS/git-uncommitted-scanner
+Project-URL: Repository, https://github.com/RootDeveloperDS/git-uncommitted-scanner
+Project-URL: Bug Tracker, https://github.com/RootDeveloperDS/git-uncommitted-scanner/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=0.50.0
+
+# 🔍 Git Uncommitted Scanner (`scanrepos`)
+
+![Python](https://img.shields.io/badge/python-3.9+-blue.svg)
+![Typer](https://img.shields.io/badge/typer-CLI-black.svg)
+![Rich](https://img.shields.io/badge/rich-Terminal-magenta.svg)
+![Textual](https://img.shields.io/badge/textual-TUI-cyan.svg)
+[![PyPI version](https://badge.fury.io/py/git-uncommitted-scanner.svg)](https://badge.fury.io/py/git-uncommitted-scanner)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+
+**A high-speed, cross-platform CLI & TUI utility that recursively deep-scans your filesystem to instantly locate Git repositories with pending uncommitted changes.**
+
+---
+
+## ⚡ Why `git-uncommitted-scanner`?
+
+Tired of discovering forgotten, uncommitted code changes in scattered workspace folders months later? `git-uncommitted-scanner` recursively hunts down pending changes across your entire filesystem with asynchronous speed, presenting them in either a clean CLI table or a high-tech interactive Terminal User Interface (TUI).
+
+<p align="center">
+  <img src="docs/images/interactive_scan.png" alt="Git Uncommitted Scanner - Interactive Neon-Cyan TUI" width="850">
+</p>
+
+---
+
+## 📦 Installation
+
+Choose the installation method that fits your environment:
+
+### Method 1: Recommended for CLI tools (`pipx` / `uv`)
+`pipx` and `uv` automatically isolate dependencies and ensure binary executable scripts are added to your system `PATH`:
+
+```bash
+# Using pipx (Recommended - automatically configures PATH)
+pipx install git-uncommitted-scanner
+pipx ensurepath
+
+# Or using uv
+uv tool install git-uncommitted-scanner
+
+# Or run instantly without installing:
+uvx git-uncommitted-scanner
+```
+
+### Method 2: Standard `pip`
+```bash
+pip install git-uncommitted-scanner
+```
+
+> [!TIP]
+> **Can't find the `scanrepos` command after installing?**  
+> You can **always** run the scanner directly through Python without modifying your PATH:
+> ```bash
+> python -m git_scanner
+> ```
+> See the [Troubleshooting & PATH Fix](#-troubleshooting--faq) section below to permanently add `scanrepos` to your terminal.
+
+---
+
+## 🚀 Usage
+
+You can run the scanner using either `scanrepos` or `python -m git_scanner`:
+
+### 1. Standard CLI Mode
+Run a rapid background scan that outputs a styled `Rich` table listing all uncommitted repositories along with branch names, modified file counts, untracked counts, and last commit age.
+
+```bash
+# Scan the current directory
+scanrepos
+
+# Scan a specific directory path
+scanrepos /path/to/your/projects
+
+# Limit search depth to 3 levels
+scanrepos /path/to/projects -d 3
+
+# Exclude specific folders (e.g. node_modules, build, vendor)
+scanrepos /path/to/projects -e "vendor,build"
+
+# Ignore repositories with only untracked files (clean worktrees)
+scanrepos -u
+
+# Scripting / Automation: Output ONLY raw paths (ideal for xargs, pipelines, CI/CD)
+scanrepos -q
+
+# Check installed version
+scanrepos --version
+
+# View all CLI options and flags
+scanrepos --help
+
+# Export results to JSON or CSV (format auto-detected by extension)
+scanrepos /path/to/projects --export scan_results.json
+scanrepos /path/to/projects --export scan_results.csv
+```
+
+<p align="center">
+  <img src="docs/images/scanning.png" alt="Git Uncommitted Scanner - Standard CLI Scanning Output" width="850">
+</p>
+
+<details>
+<summary><b>📖 Click to preview full CLI Options & Flags (<code>scanrepos --help</code>)</b></summary>
+<br>
+<p align="center">
+  <img src="docs/images/scan_help.png" alt="Git Uncommitted Scanner - CLI Help Menu" width="850">
+</p>
+</details>
+
+### 2. Interactive TUI Mode (`-i`)
+Launch the Neon-Cyan Terminal User Interface. Navigate repositories with keyboard arrows, double-click or press <kbd>Enter</kbd> to spawn a native shell terminal directly inside the highlighted workspace.
+
+```bash
+# Launch TUI in the current directory
+scanrepos -i
+
+# Launch TUI with custom path, depth limits, and exclusions
+scanrepos -i /path/to/your/projects -e "vendor,temp" -d 4
+```
+
+#### TUI Keyboard & Mouse Controls:
+* **Column Header Click**: Click any column header to sort ascending (▲) / descending (▼) by ID, Path, Branch, Modified, Untracked, or Last Commit.
+* <kbd>/</kbd> or <kbd>s</kbd> : Toggle live search/filter bar to filter repositories by name or branch in real time.
+* <kbd>Escape</kbd> : Close/dismiss search bar and restore focus to the repository table.
+* <kbd>Enter</kbd> / Double-Click / <kbd>o</kbd> : Spawn native OS terminal (`wt`, `pwsh`, `cmd`, `iTerm2`, `Terminal.app`, `gnome-terminal`, `alacritty`, `kitty`, etc.) in the selected repository.
+* <kbd>r</kbd> : Trigger an asynchronous re-scan of the target folder.
+* <kbd>q</kbd> : Quit the application.
+
+---
+
+### 3. Configuration File Support (`.gitscannerrc` / `pyproject.toml`)
+You can define persistent default exclusions and search depth in `~/.gitscannerrc`, `.gitscannerrc`, or `pyproject.toml`:
+
+```ini
+# .gitscannerrc
+[gitscanner]
+exclude = vendor, temp, test_env, cache
+max_depth = 4
+```
+
+Or in `pyproject.toml`:
+```toml
+[tool.gitscanner]
+exclude = ["vendor", "temp", "cache"]
+max_depth = 4
+```
+
+---
+
+## ✨ Key Features
+
+* **⚡ Generative Concurrency & Deep Scanning**: Traverses nested folder trees using iterative `os.scandir` DFS pruning and pipelines discoveries straight into a multi-threaded `ThreadPoolExecutor` (up to 32 concurrent workers), overlapping disk I/O with subprocess execution.
+* **🖥️ Interactive Neon-Cyan TUI**: Built with customized `Textual` components, providing smooth keyboard navigation, zebra striping, and automatic table focus on scan completion.
+* **📊 Bi-Directional Interactive Column Sorting**: Click any column header or navigate to toggle ascending (▲) and descending (▼) sort order by ID, Path, Branch, Modified files, Untracked files, or chronological Last Commit timestamp.
+* **🔍 Real-Time Live Search Overlay**: Press <kbd>/</kbd> or <kbd>s</kbd> to filter large project lists by repository path or branch in real time; dismiss with <kbd>Escape</kbd> to return to table navigation.
+* **🌐 Upstream Synchronization Telemetry**: Parses remote tracking branches to display live ahead/behind indicators (`[↑X ↓Y]`), alerting you immediately when local commits need pushing or upstream changes need pulling.
+* **💻 OS-Aware Native Terminal Launcher**: Highlight any uncommitted repository in the TUI and press <kbd>Enter</kbd>, double-click, or press <kbd>o</kbd> to spawn a native shell running `git status` inside that folder (auto-detects Windows Terminal `wt`, PowerShell 7 `pwsh`, `cmd`, macOS `iTerm2`/`Terminal.app`, Linux `gnome-terminal`, `alacritty`, `kitty`, `konsole`, etc.).
+* **🤖 Script Automation & Quiet Mode**: Added `--quiet` (`-q`) mode to suppress all rich spinners and tables, outputting only raw, newline-delimited paths for seamless piping into `xargs`, shell scripts, or CI/CD pipelines.
+* **🎯 Granular Noise Reduction**: Ignore repositories with only untracked files (`-u` / `--exclude-untracked`), exclude custom directory blacklists (`-e`), and limit traversal recursion depth (`-d`).
+* **📄 Dual JSON & CSV Data Export**: Automatically infers and exports scan data to either structured JSON (`.json`) or spreadsheet-friendly CSV (`.csv`) via `--export`.
+* **⚙️ Persistent Configuration**: Define global or project defaults in `~/.gitscannerrc`, `.gitscannerrc`, or `pyproject.toml`.
+* **🌳 Submodule & Worktree Support**: Accurately recognizes both standard `.git` directories and `.git` pointers (submodules and git worktrees).
+* **🛡️ Zero-Config Module Execution**: Built-in `python -m git_scanner` runner ensures the app runs anywhere, even on restricted or shared lab PCs where Python's `Scripts/` folder is not on system `PATH`.
+* **🪶 Zero Dependencies Bloat**: Pure Python standard library logic alongside `typer`, `rich`, and `textual` — no heavy C extensions or bloatware.
+
+---
+
+## 🛠️ Technology Stack
+
+* **Core Engine**: Python `>=3.9`, standard `subprocess`, `pathlib.Path`
+* **CLI Routing**: [`Typer`](https://typer.tiangolo.com/)
+* **Terminal Formatting**: [`Rich`](https://rich.readthedocs.io/)
+* **Interactive TUI**: [`Textual`](https://textual.textualize.io/)
+* **Build System**: `setuptools` (PEP 621 compliant)
+
+---
+
+## 🤖 Agent Ecosystem & Developer Guidelines
+
+This repository includes a structured multi-agent automation setup for continuous maintenance:
+
+* [`AGENTS.md`](AGENTS.md) — Mandatory developer & autonomous agent guidelines, zero-fake-progress rules, and PR formatting standards.
+* [`prompt-bolt.md`](prompt-bolt.md) — **GitScanner Bolt ⚡** (Performance & scan speed optimizer prompt).
+* [`prompt-evo.md`](prompt-evo.md) — **GitScanner Evo 🚀** (Product feature evolution prompt).
+* [`prompt-pallete.md`](prompt-pallete.md) — **GitScanner Palette 🎨** (TUI & CLI UX evolution prompt).
+* [`.coderabbit.yaml`](.coderabbit.yaml) — Assertive automated PR code review rules.
+* **Target PR Branch**: `Dev2Auto`
+
+---
+
+## 🔧 Troubleshooting & FAQ
+
+### `'scanrepos' is not recognized as an internal or external command`
+
+This occurs when Python installs command-line scripts to your user directory (common on shared, lab, or school PCs where administrator rights are restricted), but that directory has not yet been added to your system `PATH`.
+
+#### Quick Fix 1: Run via Python directly (Works instantly, no setup needed)
+```bash
+python -m git_scanner
+```
+*(or `python -m git_scanner -i` for TUI mode)*
+
+#### Quick Fix 2: Reinstall with `pipx` (Recommended)
+`pipx` automatically isolates CLI tools and configures your PATH:
+```bash
+pip install pipx
+pipx ensurepath
+pipx install git-uncommitted-scanner
+```
+
+#### Quick Fix 3: Add Python Scripts to your PATH manually
+
+* **Windows (PowerShell)**:
+  Run this one-liner in PowerShell to permanently add Python Scripts to your user PATH:
+  ```powershell
+  [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$((py -c 'import site; print(site.USER_BASE)') + '\Scripts')", "User")
+  ```
+  Then restart your terminal.
+
+* **Linux / macOS**:
+  Add Python bin to your `~/.bashrc` or `~/.zshrc`:
+  ```bash
+  export PATH="$HOME/.local/bin:$PATH"
+  ```
+  Then reload your shell (`source ~/.bashrc` or `source ~/.zshrc`).
+
+---
+
+## 📜 Version History & Release Notes
+
+For a complete record of all updates, bug fixes, and feature additions across releases, please refer to the **[`CHANGELOG.md`](CHANGELOG.md)**.
+
+---
+
+Built with ❤️ by [RootDeveloperDS](https://github.com/RootDeveloperDS)

git_uncommitted_scanner-0.2.0/git_scanner/__init__.py

@@ -0,0 +1,4 @@
+"""git-uncommitted-scanner package."""
+
+__version__ = "0.2.0"
+

git_uncommitted_scanner-0.2.0/git_scanner/__main__.py

@@ -0,0 +1,4 @@
+from git_scanner.main import app
+
+if __name__ == '__main__':
+    app()