Metadata-Version: 2.4
Name: gitsmith
Version: 0.3.0
Summary: Intelligent CLI tool for automated GitHub repository synchronization - clone, sync, and manage all your repos from one command
Author: Vamsi
License-Expression: MIT
Project-URL: Homepage, https://github.com/vamsi-31/gitfordge
Project-URL: Repository, https://github.com/vamsi-31/gitfordge
Project-URL: Bug Tracker, https://github.com/vamsi-31/gitfordge/issues
Project-URL: Documentation, https://github.com/vamsi-31/gitfordge#readme
Project-URL: Changelog, https://github.com/vamsi-31/gitfordge/blob/main/project_status.md
Keywords: git,github,cli,sync,clone,repository,automation,devtools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
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 :: Version Control :: Git
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
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: InquirerPy>=0.3.4
Requires-Dist: requests>=2.28.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: shellingham>=1.3.0
Dynamic: license-file

# gitsmith

<div align="center">

**Intelligent CLI Repository Synchronization Engine**

[![PyPI](https://img.shields.io/pypi/v/gitsmith?color=blue&label=PyPI&logo=pypi&logoColor=white)](https://pypi.org/project/gitsmith/)
[![Downloads](https://img.shields.io/pypi/dm/gitsmith?color=brightgreen&label=Downloads%2Fmonth&logo=pypi&logoColor=white)](https://pypi.org/project/gitsmith/)
[![Total Downloads](https://static.pepy.tech/badge/gitsmith)](https://pepy.tech/project/gitsmith)
[![Python](https://img.shields.io/pypi/pyversions/gitsmith?logo=python&logoColor=white)](https://pypi.org/project/gitsmith/)
[![CI](https://github.com/vamsi-31/gitfordge/actions/workflows/ci.yml/badge.svg)](https://github.com/vamsi-31/gitfordge/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

*Clone, update, and manage all your GitHub repositories from one beautiful command-line interface.*

</div>

---

## What is gitsmith?

`gitsmith` automates the painful process of setting up all your GitHub repositories on a new machine (or keeping them up to date). It authenticates via your GitHub token — stored securely in your OS keyring — fetches every accessible repo, compares them against your local filesystem, and **only clones what's missing** (idempotent delta synchronization).

It supports a full **interactive wizard** for humans *and* a declarative **non-interactive mode** for CI/CD pipelines.

---

## Features

| Feature | Description |
|---|---|
| **Secure Auth** | Token encrypted in OS keyring — never in plain-text files |
| **Delta Sync** | Compares remote vs local — only clones what's missing |
| **Always Dry-Run First** | See exactly what will happen before any action is taken |
| **SSH Passphrase Support** | SSH clones/pulls display passphrase prompts interactively |
| **Interactive Skip** | Deselect any repos via checkbox before executing |
| **Interactive Wizard** | Beautiful step-by-step UI with progress bars and Rich panels |
| **List Repos** | Browse your GitHub repos with stars, sizes, and flags |
| **Org Support** | Sync personal repos, organization repos, or both |
| **Concurrent Cloning** | Clone multiple repos in parallel with `ThreadPoolExecutor` |
| **Fault Tolerant** | One repo failure never crashes the whole run |
| **Token Fingerprinting** | SHA-256 fingerprints for safe token identification |
| **Regex Filtering** | `--include` / `--exclude` patterns for fine-grained control |
| **CI/CD Ready** | `--no-interactive --yes` mode for scripted pipelines |

---

## Installation

```bash
pip install gitsmith
```

> **Requires:** Python 3.9+ and Git installed in your `PATH`.

---

## Quick Start

### 1. Store your token (one time)

```bash
gitsmith auth login
```

Your token is encrypted by your OS credential manager — **never** written to a file.

> Required scopes: `repo`, `read:org`  
> Create a token at: <https://github.com/settings/tokens>

### 2. Sync all repos (interactive wizard)

```bash
gitsmith sync
```

The wizard guides you through:

```
[1/7] Authenticate with GitHub
[2/7] Select sync targets (personal / org / both)
[3/7] Configure directory + clone protocol (HTTPS or SSH)
[4/7] Fetch repository inventory from GitHub
[5/7] Dry-run preview — see all repos and their status
[6/7] Interactively deselect repos you want to skip
[7/7] Execute concurrent cloning with live progress bars
```

### 3. List all remote repos

```bash
gitsmith list
```

Displays a full table of your GitHub repos with language, stars, size, visibility, and fork/archived flags.

### 4. Check status (dry run only)

```bash
gitsmith status
```

### 5. Declarative mode (CI/CD)

```bash
gitsmith sync --token $GITHUB_TOKEN --dir ./repos --no-interactive --yes
```

---

## Commands

| Command | Description |
|---|---|
| `gitsmith sync` | Full sync — interactive wizard or declarative mode |
| `gitsmith list` | List remote repos without syncing |
| `gitsmith status` | Show sync delta without executing (dry run) |
| `gitsmith auth login` | Store GitHub token securely |
| `gitsmith auth logout` | Remove stored token |
| `gitsmith auth status` | Show auth status + token fingerprint |
| `gitsmith version` | Show version information |

---

## Sync Flags

| Flag | Short | Default | Description |
|---|---|---|---|
| `--token` | `-t` | keyring | GitHub PAT (or use keyring) |
| `--org` | `-o` | — | Target a specific organization |
| `--dir` | `-d` | `.` | Target directory for cloned repos |
| `--protocol` | `-p` | `https` | Clone via `https` or `ssh` |
| `--include` | — | — | Only repos matching this regex |
| `--exclude` | — | — | Skip repos matching this regex |
| `--update` / `--no-update` | — | off | Also pull/rebase existing repos |
| `--workers` | `-w` | `4` | Parallel clone threads (1–32) |
| `--dry-run` | — | off | Preview only, don't execute |
| `--no-interactive` | — | off | Skip wizard (for scripts) |
| `--yes` | `-y` | off | Auto-confirm after preview |
| `--verbose` | `-v` | off | Print each git command |

## List Flags

| Flag | Default | Description |
|---|---|---|
| `--token`, `-t` | keyring | GitHub PAT |
| `--org`, `-o` | — | Target organization |
| `--include` | — | Filter by regex |
| `--exclude` | — | Exclude by regex |
| `--private / --no-private` | on | Show/hide private repos |
| `--forks / --no-forks` | on | Show/hide forked repos |
| `--archived / --no-archived` | on | Show/hide archived repos |
| `--sort` | `name` | Sort by: `name`, `stars`, `updated`, `size` |

---

## SSH Support

When you choose `--protocol ssh`, gitsmith runs `git clone`/`git pull` without suppressing the terminal so that **SSH passphrase prompts appear interactively**. This means:

- Your `ssh-agent` is used automatically if it has the key loaded.
- If your key has a passphrase, Git will prompt you for it on the terminal.
- No passphrase? It just works silently.

```bash
gitsmith sync --protocol ssh
```

---

## Examples

```bash
# Sync everything interactively (recommended first run)
gitsmith sync

# Sync via SSH (passphrase prompts shown when needed)
gitsmith sync --protocol ssh

# Clone only repos containing "api" in the name
gitsmith sync --include "api"

# Pull existing repos AND clone missing ones
gitsmith sync --update

# Sync a specific organisation to a specific directory
gitsmith sync --org my-company --dir ~/work/repos

# Declarative CI/CD mode (no prompts at all)
gitsmith sync --token $GITHUB_TOKEN --no-interactive --yes --update

# List all repos sorted by stars
gitsmith list --sort stars

# List only non-fork, non-archived public repos
gitsmith list --no-forks --no-archived --no-private
```

---

## Token Security

gitsmith takes credential security seriously:

| Guarantee | Detail |
|---|---|
| **Never in files** | OS-level encrypted credential managers only |
| **Never logged** | Token values are masked in all output |
| **Fingerprinted** | SHA-256 hash (8-char truncated) for safe identification |
| **Constant-time compare** | `hmac.compare_digest` prevents timing attacks |
| **Priority chain** | CLI flag → env var `GITHUB_TOKEN` → OS Keyring → interactive prompt |

| Platform | Backend | Encryption |
|---|---|---|
| Windows | Credential Manager | DPAPI (user session key) |
| macOS | Keychain Access | AES-256 |
| Linux | Secret Service (GNOME Keyring / KDE KWallet) | Session-bound |

---

## Changelog

### v0.3.0 (2026-04-21)

- **Fix:** SSH passphrase prompts now appear interactively — no more silent hangs when cloning via SSH.
- **New:** `gitsmith list` command — browse all remote repos with stars, sizes, and filter flags.
- **New:** `gitsmith version` command — standalone version info panel.
- **New:** `get_last_commit_info` helper in `git_ops` for richer repo metadata.
- **Better CLI:** Rich help text with usage examples on every command, improved flag descriptions, SSH reminder messages.

### v0.2.0

- Delta sync engine improvements.
- Rate-limit awareness display.
- Organisation repo pagination fixes.

### v0.1.0 (2026-04-19)

- Initial release — interactive wizard, secure keyring auth, delta sync, dry-run preview, concurrent cloning.

---

## License

MIT — see [LICENSE](LICENSE)
