gitsmith

---

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

pip install gitsmith

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

---

Quick Start

1. Store your token (one time)

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)

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

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)

gitsmith status

5. Declarative mode (CI/CD)

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.

gitsmith sync --protocol ssh

---

Examples

# 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