# GitSetu Documentation (llms.txt)

This file contains the complete, unformatted markdown documentation for GitSetu. 
It is intended for consumption by Large Language Models (LLMs), AI Agents, and automated tools.

Project: GitSetu
Homepage: https://gitsetu.bhaskarjha.dev


--- START OF FILE: adr/0001-dual-ssh-routing-strategy.md ---

---
title: "ADR 0001: Dual SSH Routing"
description: "Architectural Decision Record: Dual SSH key routing via Match blocks versus include directives."
category: "adr"
slug: "adr/0001-dual-ssh-routing-strategy"
---
# ADR 0001: The Dual-Strategy SSH Routing Architecture

## Status
**Accepted** (May 2026)

## Context
GitSetu operates on a core philosophy of zero external dependencies. A critical component of its architecture is routing Git traffic through the correct SSH identity. 

There was significant debate regarding whether to rely exclusively on Git's native `core.sshCommand` (via `includeIf`) or to continue mutating the OS-level `~/.ssh/config` file to provide host aliases (e.g., `github-pro`). Theoretical audits suggested that `core.sshCommand` was sufficient and that the `~/.ssh/config` strategy was a "brittle legacy" approach.

Extensive terminal simulations were conducted to test Git's internal evaluation of `includeIf` during the `git clone` lifecycle and, critically, how external package managers interact with Git subprocesses.

## Decision
We will **permanently retain the dual-strategy architecture** (using both `core.sshCommand` and `~/.ssh/config` aliases).

### 1. Why `core.sshCommand` alone is insufficient
When external package managers (such as `go get`, `npm`, `cargo`, or `terraform init`) fetch private dependencies, they frequently spawn a `git clone` subprocess that targets a **global cache directory** (e.g., `~/.go/pkg/mod/...` or `~/.npm/...`).
Because the target directory of the clone falls *outside* the developer's mapped local workspace (e.g., `~/work/`), Git's `includeIf "gitdir:~/work/"` directive silently fails. The `core.sshCommand` is dropped, authentication defaults to the generic SSH key, and the package manager abruptly fails.

### 2. The Necessity of `~/.ssh/config`
Because Git cannot dynamically route identities for external cache directories based purely on the `pwd` of the parent process, the only mathematically sound solution is OS-level network routing.
By providing `~/.ssh/config` aliases (e.g., `Host github-pro`), developers have a definitive manual escape hatch. They can configure their package managers (e.g., via `url.insteadOf` or direct aliases) or manually clone repositories into unmapped directories while explicitly enforcing the correct identity.

## Consequences
*   **For Developers:** Future contributors and AI agents are strictly forbidden from attempting to "refactor" or remove the `~/.ssh/config` alias generation under the mistaken belief that Git's `includeIf` is a monolithic solution.
*   **For Architecture:** The complexity of maintaining two separate routing layers is accepted as a permanent, necessary cost of doing business in a flawed multi-tenant Git ecosystem.


--- END OF FILE: adr/0001-dual-ssh-routing-strategy.md ---

--- START OF FILE: adr/0002-ssh-config-include-directive.md ---

---
title: "ADR 0002: OpenSSH Include Pivot"
description: "Architectural Decision Record: Standardizing on modular Include ~/.config/gitsetu/profiles/ssh_config."
category: "adr"
slug: "adr/0002-ssh-config-include-directive"
---
# ADR 0002: The OpenSSH `Include` Directive Pivot

## Status
**Accepted** (May 2026)

## Context
As established in ADR 0001, GitSetu must generate OS-level SSH host aliases (`Host github-pro`) to provide a manual fallback for complex dependency cloning workflows. 

Historically, GitSetu implemented this by using inline `awk` commands to rip open the user's global `~/.ssh/config` file, locate specific `[gitsetu:managed:start]` markers, and surgically replace the text blocks. 

This approach was identified as a critical architectural vulnerability (a "ticking time bomb"). Complex user configurations, unexpected formatting, or process interruptions during the atomic `mv` operation posed a massive risk of corrupting the user's global network access configuration. This violated GitSetu's core "Zero-Trust" mandate.

## Decision
We will **migrate SSH alias orchestration exclusively to the OpenSSH `Include` directive.**

1.  GitSetu will cease all inline mutation of `~/.ssh/config` blocks.
2.  All generated aliases will be written to a dedicated, isolated file: `~/.config/gitsetu/profiles/ssh_config`.
3.  During setup, GitSetu will perform a one-time check to ensure the directive `Include ~/.config/gitsetu/profiles/ssh_config` exists at the **absolute top** of the user's `~/.ssh/config` file.

### Why the Absolute Top?
OpenSSH configuration parsing operates on a **"first-match wins"** rule. If the `Include` directive is placed at the bottom of the file, any generic blocks (e.g., `Host *` or `Host github.com`) defined earlier by the user will lock in their parameter values, causing GitSetu's aliases to be silently overridden. Placing the `Include` directive at the top guarantees precedence while cleanly isolating the tool's footprint.

### Sandbox Validation
Testing confirmed that if the included file (`~/.config/gitsetu/profiles/ssh_config`) does not exist (e.g., following a `gitsetu teardown` operation), OpenSSH gracefully and silently ignores the `Include` directive without crashing or terminating the SSH handshake.

## Consequences
*   **For Security:** Complete Zero-Trust isolation is achieved. GitSetu no longer risks corrupting the user's legacy SSH configurations.
*   **For Maintainability:** The Bash script logic in `lib/ssh.sh` becomes drastically simpler, eliminating the need for brittle, multi-line `awk` parsers.
*   **For Compatibility:** The `Include` directive requires OpenSSH 7.3+ (released August 2016). This is deemed an acceptable minimum requirement for modern Git multi-tenant environments.


--- END OF FILE: adr/0002-ssh-config-include-directive.md ---

--- START OF FILE: core-engines/credential-broker.md ---

---
title: "Credential Broker"
description: "OS keychain integration and encrypted credential vault storing personal access tokens securely."
category: "core-engines"
slug: "core-engines/credential-broker"
---
# Credential Broker Engine

**Native OS keychain isolation preventing HTTPS Personal Access Token (PAT) cross-profile pollution.**

Corporate network firewalls frequently block outbound connections on SSH Port 22 entirely. This forces developers to clone, push, and pull repositories using HTTPS protocols backed by Personal Access Tokens (PATs).

However, operating system credential stores natively introduce a critical vulnerability when managing multiple tokens across overlapping environments. GitSetu includes a specialized **Credential Broker Engine** to resolve this challenge permanently.

---

## The Operational Vulnerability

When authenticating over HTTPS, Git streams a credential request directly to your underlying operating system (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

```
[ git push https://github.com/org/repo.git ]
                     │
                     ▼
        [ Upstream Request: "github.com" ]
                     │
                     ▼
[ OS Keychain blindly returns first cached token ]
                     │
                     ▼
    [ Return payload: Personal Token ]
                     │
                     ▼
       [ HTTP 403 Forbidden Error ]
```

Because external keychains key authentication strictly off the base domain string (`github.com`), they blindly return the first matching token encountered. You end up attempting to authenticate against an enterprise repository using your personal access token, raising persistent, confusing access errors.

---

## The GitSetu Intercept Architecture

GitSetu intercepts this systemic failure by registering itself as a proxy credential helper within your dynamically mapped configuration layers.

Inside your target `.gitconfig` bounds, GitSetu statefully compiles:
```ini
[credential]
    helper = "gitsetu credential"
```

### The Isolated Resolution Flow

1. **Trigger Operation:** You execute `git push` over HTTPS inside a managed workspace folder.
2. **Helper Interception:** Git streams an authentication verification payload directly to the configured credential helper.
3. **Context Evaluation:** GitSetu leverages its optimized path-matching algorithm to identify the active profile context instantly.
4. **Namespaced Query:** Instead of requesting credentials for `github.com` from the OS, GitSetu constructs an isolated, unique namespace query: `gitsetu:work:github.com`.
5. **Target Delivery:** The OS keychain (macOS Keychain, Linux Secret Service, or Windows Git Credential Manager) returns the exact token explicitly mapped to your `work` profile context.
6. **Execution Success:** GitSetu passes the isolated token payload back to Git. Upstream communication succeeds flawlessly.

> [!NOTE]
> **Windows Credential Manager Integration:**
> On Windows (Git Bash), GitSetu automatically configures `credential.helper = manager`, natively delegating to Microsoft's **Git Credential Manager (GCM)** backed by Windows DPAPI and Windows Credential Manager.

---

## Token Lifecycle Management

To securely seed or update a Personal Access Token within an isolated profile scope, you can:
1. **Interactive Setup:** Enter your PAT when prompted during the interactive `gitsetu setup` wizard.
2. **Headless Profile Registration:** Provide credentials when invoking profile commands:
   ```bash
   gitsetu profile add work --email=dev@company.com --dir=~/work
   ```
3. **Standard Git Credential Helper Interface:** Store or retrieve credentials directly via standard Git credential protocol inputs:
   ```bash
   printf "protocol=https\nhost=github.com\nusername=dev-corp\npassword=PAT_TOKEN\n" | gitsetu credential store
   ```

### Encrypted Fallback Storage
In environments where native OS keychain facilities are absent (such as headless Linux or minimal WSL containers), GitSetu securely falls back to a restricted credential vault at `~/.config/gitsetu/.tokens`. This file is strictly enforced with `chmod 600` permissions (read/write only by the current user) immediately upon creation, preventing world-readable token exposure. Passwords and tokens are never stored in plain-text global configuration files.


--- END OF FILE: core-engines/credential-broker.md ---

--- START OF FILE: core-engines/identity-routing.md ---

---
title: "Identity Routing"
description: "Hierarchical includeIf routing engine mapping repository working directories to isolated Git identities."
category: "core-engines"
slug: "core-engines/identity-routing"
---
# Identity Routing Engine

**A deep dive into directory-scoped Git conditional mechanics and native credential switching.**

At the core of GitSetu's magical context-switching capability lies a seamless fusion of standard Git configuration files with advanced conditional file inclusion rules.

Unlike brittle wrapper utilities that alias the `git` binary or long-running supervisor daemons that monitor your file descriptors, GitSetu shifts runtime evaluation entirely to Git itself.

---

## The Routing Architecture

When you provision a workspace profile via `gitsetu setup`, GitSetu statefully compiles your global configuration file (`~/.gitconfig`), injecting a structured conditional routing table.

```ini
[gitsetu:managed:start]
[user]
    useConfigOnly = true

[init]
    defaultBranch = main

# Global Fallback Identity (unmapped directories)
[include]
    path = "~/.config/gitsetu/profiles/personal.gitconfig"

# Directory-Scoped Conditional Interceptors
[includeIf "gitdir:~/work/"]
    path = "~/.config/gitsetu/profiles/work.gitconfig"

[includeIf "gitdir:~/clients/acme/"]
    path = "~/.config/gitsetu/profiles/acme.gitconfig"
[gitsetu:managed:end]
```

### How Runtime Evaluation Operates

1. **Working Directory Transition:** You navigate your shell into `~/work/api-service/`.
2. **Git Operation Intercept:** You execute any standard git command (e.g. `git clone`, `git fetch`, or `git commit`).
3. **Path Matching:** Git natively evaluates `~/.gitconfig` top-down. Upon encountering `includeIf "gitdir:~/work/"`, it verifies if the local repository resides within that absolute tree bounds.
4. **Target Inclusion:** Because the bounds match, Git dynamically parses and applies the target profile configuration file (`~/.config/gitsetu/profiles/work.gitconfig`) mid-flight.

---

## Inside the Profile Payload

The isolated target file (`work.gitconfig`) contains your precise overrides:

```ini
[user]
    name = Corporate Author Name
    email = dev@company.com
[core]
    # Injects the exact cryptographic key context required by this profile (safe space-quoted)
    sshCommand = ssh -F ~/.ssh/config -o IdentitiesOnly=yes -i "~/.ssh/id_ed25519_work"
```

This absolute separation of concerns guarantees that **personal sandbox credentials never leak into corporate repositories**, while preventing single-key remote auth failures.

---

## Path Resolution Safeguards & Zero-Trust Architecture

Because cross-platform filesystems handle casing, symlinks, and trailing paths differently, GitSetu applies strict compilation guard rails:
- **Trailing Slashes:** Every compiled `gitdir:` path string strictly terminates with a `/` character to ensure deep sub-folder recursion acts properly.
- **Tilde Expansion:** Standardizes shell `$HOME` prefixes to absolute directory markers to stop parsing errors across disparate terminal environments.
- **Windows Case-Insensitive Matching (`gitdir/i:`):** On Windows / Git Bash, GitSetu automatically compiles `gitdir/i:` instead of `gitdir:`. Because Windows filesystems (NTFS) are case-preserving but case-insensitive, this ensures that directory matching never breaks if paths differ in casing (e.g. `C:/Users` vs `c:/users`).
- **Canonical Drive Letter Normalization:** Converts Windows paths (`/c/Users/...` or `c:\users\...`) into canonical `C:/Users/...` format, which is fully recognized and resolved by native Win32 `git.exe` across both Git Bash and Windows native shells (PowerShell, CMD).
- **Virtualization Support:** Silently filters out malformed line endings and maps target workspace trees across Windows Subsystem for Linux (WSL) boundaries flawlessly.

### Automatic Workspace Directory Provisioning (`mkdir -p`)
When registering a new profile (interactively in `gitsetu setup` or via `gitsetu add`), GitSetu automatically checks if the declared target directory exists on disk. If absent, it provisions the directory hierarchy via `mkdir -p` (while respecting `--dry-run` invariants), eliminating "directory does not exist" failures before cloning or committing.

### Longest-Prefix Match Routing
When nested workspace directories exist (e.g., a general work directory `~/work/` and a nested client project `~/work/clients/acme/`), GitSetu's routing, prompt engine, and pre-commit guard employ a deterministic longest-prefix match algorithm. The most specific directory boundary wins: Git evaluates conditional rules sequentially, and GitSetu tools compute matching prefix lengths to ensure the deeper child profile takes absolute precedence over the parent. On Windows and macOS, path matching is case-insensitive, avoiding casing drift.

### Multi-Profile Persistence & Re-hydration
Running `gitsetu setup` multiple times is safe and non-destructive. GitSetu automatically loads and re-hydrates existing profiles from `~/.config/gitsetu/profiles.conf`, preserving their names, emails, keys, and directory bindings in memory. Users can review, adjust, or append profiles without overwriting previously configured identities.

### Co-existence with Pre-Existing Manual `includeIf` Setups
For developers transitioning from hand-crafted `includeIf` directives and custom `.gitconfig` files:
1. **Zero-Destruction Boundary:** GitSetu encapsulates all generated rules strictly within `# [gitsetu:managed:start]` and `# [gitsetu:managed:end]`. Any manual `includeIf` rules, aliases, and settings outside this block are never altered, deleted, or reordered.
2. **Top-Down Sequential Precedence:** Git evaluates `~/.gitconfig` sequentially from top to bottom. Because GitSetu's managed block is appended at the end of `~/.gitconfig`, GitSetu profiles take precedence for directories they manage, ensuring correct SSH key and identity routing. All directories managed exclusively by your manual `includeIf` continue to operate normally.
3. **Automated Discovery Migration:** Running `gitsetu setup --auto` uses GitSetu's built-in discovery engine (`lib/discovery.sh`) to scan existing manual `includeIf` directives in `~/.gitconfig` and existing SSH keys in `~/.ssh/`. It automatically imports existing directory mappings and identities into the profile registry, eliminating manual re-configuration.
4. **Clean Reversibility:** If you ever decide to remove GitSetu, executing `gitsetu teardown` excises only the managed block, restoring your original manual configuration completely intact.

### Profile Teardown, Unmounting & Orphan Pruning
When a profile is removed via `gitsetu remove <label>`:
1. The profile entry is deleted from `profiles.conf`.
2. Its conditional `includeIf` block is surgically unmounted from `~/.gitconfig`.
3. Its dedicated OpenSSH host block is excised from `~/.config/gitsetu/profiles/ssh_config`.
4. Its profile configuration file `~/.config/gitsetu/profiles/<label>.gitconfig` is permanently pruned from disk.
5. Any unreferenced orphaned `.gitconfig` files in `profiles/` are pruned automatically to prevent configuration clutter.


--- END OF FILE: core-engines/identity-routing.md ---

--- START OF FILE: core-engines/precommit-guard.md ---

---
title: "Pre-Commit Guard"
description: "Deterministic pre-commit hook preventing cross-identity commit pollution and secret leakage."
category: "core-engines"
slug: "core-engines/precommit-guard"
---
# Pre-Commit Identity Guard Engine

**Fail-closed verification interceptor stopping wrong-author commits from hitting your repository history.**

While directory-scoped configuration routing acts as an incredibly reliable dynamic baseline, multi-state configuration drift remains a real vulnerability. 

If a developer runs manual one-off override commands inside a local project folder (e.g., `git config user.email "personal@example.com"`), Git's native precedence engine prioritizes local repository flags over global profile rules. To prevent these localized state overrides from leaking unauthorized identities into public commit history, GitSetu deploys an uncompromising final boundary: the **Identity Guard Engine**.

---

## Fail-Closed Intercept Flow

During initial installation or execution of the `gitsetu guard --install` subcommand, GitSetu maps a high-speed verification interceptor directly into your global Git configuration bounds (`core.hooksPath`).

```
[ Developer executes: git commit -m "feat: core module" ]
                           │
                           ▼
          [ Pre-Commit Hook Interception ]
                           │
                           ▼
  [ Rapid lookup of expected profile state for path ]
                           │
                           ▼
  [ Compares expected profile email vs actual email ]
                           │
             ┌─────────────┴─────────────┐
             ▼                           ▼
       [ MATCHES ]                 [ DIVERGES ]
             │                           │
             ▼                           ▼
     [ Commit Succeeds ]       [ INSTANT FATAL ABORT ]
```

### The Terminal Experience
When configuration divergence is intercepted, execution aborts instantly with high-visibility diagnostic output:

```text
$ git commit -m "wip: core patch"
[GitSetu Guard] BLOCKING COMMIT! Identity mismatch detected.
Expected Email: dev@company.com (Target Profile: 'work')
Active Runtime Email: personal@example.com (Source: local .git/config override)

Action Required: Run 'gitsetu doctor' or strip local config overrides.
```

---

## Ecosystem Virtualization Integration

Deploying global `core.hooksPath` directives frequently breaks localized team development tooling. 

GitSetu's intercept engine is architected to act as a **transparent pass-through proxy**. After verifying active identity boundaries successfully, the hook automatically identifies and triggers project-level execution hooks (e.g., `husky`, `lefthook`, or `pre-commit` runners), guaranteeing localized linting and testing pipelines run completely uninhibited.

---

## High-Performance Execution & Invariants

Because commit validation occurs inline multiple times a day, execution overhead must remain minimal. 

The Identity Guard is compiled purely in native, un-subshell-dependent **Bash 3.2**. By directly scanning internal configuration parameters without spinning up sub-processes or external interpreters, total evaluation completes in **`< 2 milliseconds`**, rendering the security verification entirely invisible during normal workflows.

### Longest-Prefix Match Routing
If multiple managed profile directories nest within each other (e.g., `~/work/` and `~/work/client-project/`), the guard uses a longest-prefix match algorithm to identify the deepest matching directory boundary. Commits inside `~/work/client-project/` are strictly enforced against the client profile email rather than the parent work profile.

### Case-Insensitive Directory Matching
On Windows and macOS, filesystems are case-insensitive. The guard automatically applies case normalization to both the current repository path and the configured profile workspace paths before prefix evaluation, ensuring commits aren't erroneously blocked due to casing differences (`C:/Work` vs `c:/work`).

### Dynamic Profile Email Resolution
To eliminate configuration drift if a user manually edits `~/.config/gitsetu/profiles/<label>.gitconfig` after setup, the guard dynamically re-reads the active `user.email` from the profile's `.gitconfig` file at commit time. This ensures the guard always validates against the live configuration rather than relying on stale registry cache values.

---

## Lifecycle Commands

Supervise the guard deployment natively via targeted subcommands:

```bash
# Natively mounts the global validation boundary
gitsetu guard --install

# Disables global interception cleanly
gitsetu guard --uninstall
```


--- END OF FILE: core-engines/precommit-guard.md ---

--- START OF FILE: core-engines/ssh-orchestrator.md ---

---
title: "SSH Orchestrator"
description: "Automated OpenSSH key generation, ~/.ssh/config profile management, and multi-host multiplexing."
category: "core-engines"
slug: "core-engines/ssh-orchestrator"
---
# SSH Orchestrator Engine

**Automated multi-key generation, native agent pre-loading, and zero-trust configuration isolation.**

Managing multiple SSH keys manually is highly error-prone. Standard workflows require generating distinct keys using specific CLI arguments, tracking permissions, and manually modifying host blocks in your global `~/.ssh/config` file.

GitSetu completely automates this lifecycle, bridging robust cryptographic security with absolute layout isolation.

---

## 1. Automated Key Bootstrapping

During profile creation (`gitsetu setup`), GitSetu queries if you require distinct SSH credentials for the workspace. It natively supports two primary cryptographic paths:

### ED25519 Software Signatures
Generates highly secure, modern software keys using optimal cryptographic curves:
```bash
ssh-keygen -t ed25519 -C "profile-identifier" -f ~/.ssh/id_ed25519_<label> -N ""
```

### Hardware Keys (FIDO2 / YubiKey)
Bootstraps highly tamper-resistant resident keys backed by hardware tokens:
```bash
ssh-keygen -t ed25519-sk -O resident -C "profile-identifier" -f ~/.ssh/id_ed25519_sk_<label>
```
*(For a complete breakdown of hardware key workflows, consult the [Hardware Keys Guide](/docs/guides/hardware-keys)).*

---

## 2. The OpenSSH `Include` Pivot & Safe Quoting

Historically, utilities modified `~/.ssh/config` files inline using search-and-replace scripts. This design pattern introduces catastrophic risk, frequently corrupting user configurations during unexpected exit events.

GitSetu resolves this by leveraging OpenSSH 7.3+'s native **`Include` directive** to enforce a zero-trust network boundary.

### Stage 1: The Initial Hook Injection
GitSetu inspects your global config once. It prepends a single line to the top of your file:
```ini
Include ~/.config/gitsetu/profiles/ssh_config
```

### Stage 2: Sandboxed Orchestration
All customized host targets, host mapping blocks, and explicit key links are fully sandboxed inside GitSetu's localized state directory:

```ini
# ~/.config/gitsetu/profiles/ssh_config (Fully Automated)
Host github.com-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes
```

This ensures your primary SSH configuration remains completely untouched, allowing clean profile teardowns and safe multi-environment usage.

### Safe SSH Key Path Quoting
When SSH key paths contain spaces (e.g. `C:/Users/First Last/.ssh/...` or `~/My Keys/id_ed25519`), OpenSSH CLI commands can suffer from argument splitting. GitSetu automatically wraps key paths in escaped double-quotes within `core.sshCommand = ssh -i "..."` and when exporting `GIT_SSH_COMMAND="ssh -i \"...\""` in `gitsetu run`, preventing command parsing errors across all platforms.

---

## 3. Agent Virtualization, Platform Permissions & Dual Routing

Loading multiple keys concurrently often saturates remote authentication boundaries, returning `Too many authentication failures` errors during handshake negotiations.

GitSetu's compiler natively intercepts and resolves these session blocks:
- **`IdentitiesOnly = yes`:** Hardcoded into every generated target file to prevent OpenSSH from blindly presenting unmapped keys cached in the global agent socket.
- **Keychain Injection:** Automates passphrase pre-loading on macOS (`UseKeychain yes`) and Linux agents to optimize daily workflows seamlessly.
- **Windows NTFS Permission Tolerance:** Under POSIX systems, OpenSSH mandates strict `0600` permissions on private keys. Under Git Bash on Windows NTFS filesystems, POSIX permissions default to `644`. GitSetu's diagnostic and verification engines natively recognize this environment, tolerating `644` without producing false-positive permission warnings.
- **Dual Routing Architecture (ADR-0001):** Combines directory-scoped `core.sshCommand` with `~/.ssh/config` host aliases (`github.com-<label>`), ensuring seamless compatibility both inside mapped workspaces and for external dependency package manager clones (`go get`, `npm`, `cargo`) outside mapped folders.


--- END OF FILE: core-engines/ssh-orchestrator.md ---

--- START OF FILE: enterprise/product-roadmap.md ---

---
title: "Product Roadmap"
description: "Strategic milestones, protocol enhancements, and enterprise roadmap for GitSetu."
category: "enterprise"
slug: "enterprise/product-roadmap"
---
# Product Roadmap (2026 Vision)

**Charting the trajectory from 82/100 to an unassailable 100/100 Enterprise Identity Platform.**

Our mission is to make identity leakage structurally impossible. GitSetu currently holds an industry-leading position for zero-dependency identity orchestration, yet significant expansion opportunities exist within the enterprise, CI/CD, and deeper IDE integration layers.

This research-driven roadmap synthesizes competitive analysis, developer pain-point research, and macro identity security trends to chart the complete path forward over the next 18 months.

---

## The Strategic Baseline

Based on exhaustive ecosystem analysis (May 2026), GitSetu maintains a composite feature/safety score of **82/100**, acting as the most comprehensive identity manager for macOS and Linux engineers.

However, the industry landscape reveals escalating threat vectors:
- **64% of credentials** leaked in 2022 remained actively valid four years later due to stagnant key rotation practices.
- **Non-Human Identities (NHI)** in CI/CD environments now outnumber human identities **144:1**, representing the primary target for credential compromise.

Our target is a flawless **100/100**. A developer using GitSetu should never have to manually manage key generation, rotation, identity switching, or pipeline authentication ever again. The bridge must become entirely invisible.

---

## Foundation: Completed in v1.0.0

The following architectural hardening milestones established our enterprise baseline, backed by 36 automated regression and empirical test suites (250+ assertions) and a 31-phase live Windows Sandbox empirical audit (107/107 checks passed):
- **Zero-Trust Identity Guard**: Hard pre-commit intercepts preventing dual-state leaks with longest-prefix directory matching, Windows/macOS case-insensitivity, and dynamic email re-reading.
- **Single Source of Truth (SSOT)**: Dynamic resolution via isolated `.gitconfig` files without registry polling.
- **Native Windows PowerShell Distribution**: Shipped native `install.ps1` & `uninstall.ps1` installers, automated Command Prompt (`gitsetu.cmd`) and PowerShell (`gitsetu.ps1`) shims in `%LOCALAPPDATA%\gitsetu\bin`, and User `PATH` environment management.
- **Package Formula Definitions**: Authored official Homebrew formula (`packaging/homebrew/gitsetu.rb`) and Windows Scoop manifest (`packaging/scoop/gitsetu.json`).
- **Headless & Dotfiles Automation**: Scriptable, non-interactive profile provisioning via `gitsetu add` and `gitsetu profile add` backed by POSIX directory concurrency locking (`profiles.lock`).
- **Automated Workspace Provisioning**: Auto-creates missing workspace directories (`mkdir -p`) upon profile registration, with clean unmounting and pruning on profile deletion.
- **Multi-Profile Persistence & Re-hydration**: Preserves and re-hydrates existing profiles across multiple `gitsetu setup` runs.
- **Safe SSH Space Quoting**: Double-quotes key paths with spaces in `core.sshCommand` and `GIT_SSH_COMMAND`.
- **SSH Commit Signing**: Full native support for SSH-based cryptographic commit signatures (`gpg.format = ssh`, `commit.gpgsign = true`).
- **Cross-Platform Normalization**: Native Windows drive path conversion (`pwd -W`), case-insensitive path comparisons on Windows and macOS.
- **Unified Global Lifecycle**: Complete signal trapping (`EXIT/SIGINT/SIGTERM`) ensuring zero lock leaks.
- **POSIX Concurrency Hardening**: Atomic `mv` operations eliminating Time-of-Check to Time-of-Use race conditions.
- **Bash 3.2 Array Panic Prevention**: Native C-style POSIX loop structures replacing fragile subshell bounds.
- **Path Injection Prevention**: Strict newline sanitization preventing INI boundary corruption.
- **Encrypted State Export**: AES-256 OpenSSL vault packaging (`gitsetu backup` / `gitsetu restore`).
- **Empirical Sandbox Verification Matrix**: 36 automated regression test suites and isolated Windows Sandbox test harness (36/36 suites passing 100% green, 107/107 sandbox audit checks passed).

---

## Phase 1: Zero-Friction Onboarding & Universal Distribution

**Goal:** Eliminate all adoption friction by ensuring GitSetu is instantly discoverable, installable, and trusted across all developer environments without requiring git clones or elevated permissions.

- **Single-File Bundled Binary (`gitsetu-standalone` / `make dist`):** 
  - Release an automated build step that inlines all `lib/*.sh` modules into a single, self-contained executable script.
  - Allows direct download without cloning the git repository:
    ```bash
    curl -sL https://gitsetu.bhaskarjha.dev/bin/gitsetu -o ~/.local/bin/gitsetu && chmod +x ~/.local/bin/gitsetu
    ```
- **Homebrew Tap & Core Ingestion:** Launch the official `bhaskarjha-dev/homebrew-tap` repository and initiate submission to `homebrew/core` (`brew install gitsetu`).
- **Dedicated Community Package Managers:**
  - **Windows Scoop:** Publish `packaging/scoop/gitsetu.json` to official Scoop buckets (Main / Extras).
  - **Microsoft Winget:** Submit the official `BhaskarJha.GitSetu` manifest to Microsoft's `winget-pkgs` repository (`winget install BhaskarJha.GitSetu`).
  - **Arch Linux AUR:** Publish official `PKGBUILD` to `aur.archlinux.org/gitsetu.git` (`yay -S gitsetu`).
  - **Nix / Nixpkgs Flake:** Introduce a standard `flake.nix` in the repository root for reproducible, zero-dependency NixOS execution (`nix run github:bhaskarjha-dev/gitsetu`).
  - **npm / npx Wrapper:** Publish a thin npm binary wrapper (`npx gitsetu setup` / `npm i -g gitsetu`) for JavaScript and fullstack web developers.
- **GitHub CLI Extension (`gh gitsetu`):** Publish `gh extension install bhaskarjha-dev/gh-gitsetu`, allowing developers working inside GitHub CLI workflows to run `gh setu` / `gh gitsetu setup` natively.
- **Smart Zero-Prompt Auto-Discovery (`gitsetu init --auto`):** Expand the discovery engine in `lib/discovery.sh` into an instant, non-interactive one-shot setup command that auto-detects existing Git identities, SSH keys, and workspace folders (`~/work`, `~/personal`), applying a recommended zero-trust configuration in under 1 second.
- **Sponsorship & Governance:** Establish a formal Technical Steering Committee and define open-source contribution guidelines to guarantee long-term operational sustainability.

---

## Phase 2: Parity & Ecosystem UX

**Goal:** Introduce modern UX interaction paradigms, visual tools, and cross-tool integration points expected from premium developer workflows.

- **Web Config Visualizer & Generator:** Deploy an interactive browser-based profile designer on `gitsetu.bhaskarjha.dev` that provides live previews of generated `.gitconfig` and OpenSSH directives, outputting customized 1-line installation commands.
- **Fuzzy Profile Switching (`fzf`):** Implement interactive, ultra-fast `fzf`-powered runtime profile selection (`gitsetu switch`).
- **Native VS Code Extension:** Publish an official VS Code extension to surface the active profile directly within the editor status bar, halting commits visually within the GUI if identities misalign.
- **PGP / GPG Key Auto-Wiring:** Extend commit signing capabilities beyond native SSH to automatically wire classical PGP / GPG key targets on a per-profile basis.
- **Machine-Readable API (`--json`):** Expose all diagnostic and structural queries (`gitsetu status --json`, `gitsetu doctor --json`) via structured JSON payloads to empower community tooling and editor plugins.

---

## Phase 3: The Enterprise Moat

**Goal:** Build asynchronous defensive capabilities no competitor is architecturally positioned to match.

- **Automated Key Rotation Engine:** Implement scheduled, automated cryptographic key replacement workflows (`gitsetu rotate --every 90d`). The engine will natively rotate underlying signatures and swap OpenSSH configuration hooks completely transparently.
- **Headless CI/CD Mode:** Release a dedicated GitHub Action / GitLab CI runtime flag (`gitsetu ci-init`) that natively provisions ephemeral, tightly-scoped identity contexts on temporary CI runners, automatically tearing them down on execution exit.
- **Pre-Push Secret Scanning:** Expand the existing Identity Guard hook structure to actively scan outbound staged diffs for accidental Personal Access Token or SSH private key injections.
- **Append-Only Audit Log:** Establish a tamper-evident, locally written compliance log (`~/.local/share/gitsetu/audit.log`) tracking all identity switches and cryptographic generation events.

---

## Phase 4: Vision Completion (100/100)

**Goal:** Achieve total ecosystem saturation and enterprise deployment scale.

- **Cross-Platform Native Wrapper:** Develop a lightweight, compiled proxy (`gitsetu-bin`) to manage the core Bash libraries, enabling native Windows execution and direct binary distribution via winget/scoop.
- **JetBrains Plugin Suite:** Mirror the VS Code extension capabilities seamlessly into IntelliJ, PyCharm, WebStorm, and GoLand IDE ecosystems.
- **Team-Level Cloud Synchronization:** Deploy an opt-in, highly encrypted cloud vault bridging service to allow instant machine-to-machine state provisioning (excluding private keys).

---

## Achieving 100/100

A tool that successfully obliterates an entire category of security friction is not merely the tool with the most raw features. It is the tool that lives silently on every machine, integrates seamlessly within every manager, and guards every repository implicitly.

GitSetu's trajectory shifts it from an **identity profile switcher** directly into the **Foundational Security Layer** for modern developer operations.

---

## ❌ Out of Scope / Rejected 

To maintain its extreme focus and zero-dependency reliability, GitSetu explicitly rejects the following features from the roadmap indefinitely:

- **Historical Commit Sanitizer (`gitsetu sanitize`):** Users frequently request the ability to rewrite Git history to remove leaked personal emails. **Rejected.** Rewriting history natively in pure Bash 3.2 is wildly dangerous, highly complex, and risks catastrophic repository corruption. We defer this entirely to the official Python-based `git-filter-repo` tool.


--- END OF FILE: enterprise/product-roadmap.md ---

--- START OF FILE: enterprise/security-privacy.md ---

---
title: "Security & Privacy"
description: "Threat model, air-gapped deployment guarantees, zero-telemetry policy, and audit trail specifications."
category: "enterprise"
slug: "enterprise/security-privacy"
---
# Enterprise Security & Privacy

**Uncompromising Zero-Trust safeguards built to pass rigorous organizational and CISO audits seamlessly.**

GitSetu manages highly sensitive cryptographic boundaries, orchestrating private SSH keys, executing HTTPS credential injections, and modifying global environment states. Operating within these domains requires a structurally paranoid architectural posture. 

GitSetu is deliberately engineered to be transparent, offline, and functionally immutable.

---

## 1. Absolute Zero Telemetry

GitSetu does not "phone home."
- **Zero Analytics:** The codebase contains no telemetry payloads, usage trackers, or crash reporting pipelines.
- **Zero External Runtimes:** Execution requires no cloud infrastructure or backend synchronization servers.
- **Strict Network Boundary:** The *only* network outbound call GitSetu natively invokes is explicitly user-triggered via the `gitsetu update` command, which fetches raw verified source code dynamically over standard TLS/HTTPS bounds natively from the verified GitHub repository.

## 2. Zero-Trust SSH Isolation & Safe Command Quoting

Standard configuration utilities often manipulate global `~/.ssh/config` structures via aggressive regex replacements, risking catastrophic corruption of enterprise host routing blocks.

GitSetu strictly isolates operations using an **OpenSSH Include Pivot**. It injects a single `Include ~/.config/gitsetu/profiles/ssh_config` directive into your global configuration. All dynamically generated key aliases, Host targets, and isolation flags (`IdentitiesOnly yes`) are tightly sandboxed within localized files. If GitSetu is purged, your global SSH config remains mathematically uncorrupted.

Furthermore, GitSetu prevents CLI argument splitting by strictly wrapping SSH key paths containing whitespace characters in escaped double-quotes within `core.sshCommand` and runtime `GIT_SSH_COMMAND` exports.

## 3. Atomic Concurrency Integrity

To support highly concurrent headless CI/CD runners or rapid execution within multiplexed terminal sessions (`tmux`/`zellij`), GitSetu protects all filesystem state changes utilizing atomic POSIX primitives.

- **Write Isolation:** Mutating global blocks writes heavily to `$TMPDIR` isolation bounds before triggering single-cycle `mv` atomic swaps.
- **State Locks:** Cross-process conflicts are entirely mitigated using localized `mkdir` execution locks (`profiles.lock`) with PID inspection and automatic stale-lock eviction, strictly guaranteeing that simultaneous commands across parallel processes never corrupt state pipelines.

## 4. Protected Credential Storage

GitSetu enforces a strict policy against storing authentication payloads in plain text.
The native **Credential Broker Engine** routes Personal Access Tokens (PATs) securely directly into your operating system's native encrypted security enclaves:
- **macOS:** Apple Keychain Access (`security add-generic-password`).
- **Windows:** Microsoft Git Credential Manager (GCM) backed by Windows DPAPI / Windows Credential Manager (`credential.helper = manager`).
- **Linux:** Native Secret Service DBus API (`secret-tool`).
- **Fallback Storage:** When native keychains are unavailable, tokens are written to an isolated vault file at `~/.config/gitsetu/.tokens` enforced with strict `chmod 600` permissions (readable only by the file owner).

## 5. Fail-Closed Identity Guard & Orphaned Config Pruning

- **Pre-Commit Enforcement:** The global pre-commit hook acts as a fail-closed interceptor, halting commits with an instant fatal abort if the staged commit author email diverges from the directory-scoped profile email. It dynamically resolves nested directory trees via longest-prefix matching and re-reads live profile email definitions to prevent configuration desync.
- **Orphan Pruning:** Removing a profile (`gitsetu remove <label>`) cleanly unmounts conditional `includeIf` directives from `~/.gitconfig`, prunes corresponding `.gitconfig` files from `~/.config/gitsetu/profiles/`, and purges orphaned configuration remnants.

## 6. End-to-End Cryptographic Vaults

When operators export GitSetu state architecture via the `gitsetu backup` command, all compiled targets—and more critically, the private software SSH keys—are aggressively bundled into a compressed target payload.

GitSetu mandates that this payload is encrypted instantaneously using the host system's native `openssl` binaries. It utilizes **AES-256-CBC** cryptography scaled via heavy `-pbkdf2` derivation loops, rendering the offline vault mathematically secure against brute-force extraction attempts.

## 7. Transparent Auditable Execution

Pre-compiled binary toolchains obscure their execution paths, forcing security analysts to rely on trust or reverse-engineering toolkits.

Because GitSetu is compiled entirely in pure, un-obfuscated POSIX **Bash 3.2**, organizational security engineers can transparently audit the entire operational chain simply by reading the plain-text shell source payload prior to deployment.


--- END OF FILE: enterprise/security-privacy.md ---

--- START OF FILE: getting-started/installation.md ---

---
title: "Installation"
description: "Installation guides across 9 distribution channels including Homebrew, WinGet, Scoop, AUR, Nix, and native scripts."
category: "getting-started"
slug: "getting-started/installation"
---
# Installation

GitSetu is designed to be as lightweight and accessible as possible. It runs natively across macOS, Linux, and Windows with zero external runtimes (no Node.js, Python, or Go required for shell installations). On Windows, the only prerequisite is **Git for Windows**.

---

## 1. Quick Onboarding (Zero-Dependency Shell Installers)

### macOS & Linux (POSIX Bash)
Run in your standard terminal (Terminal, iTerm2, Alacritty, Kitty):
```bash
curl -sL https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/install.sh | bash
# Or via custom domain:
# curl -sL https://gitsetu.bhaskarjha.dev/install | bash
```

### Windows (Native PowerShell)
Open **PowerShell**, **Windows Terminal**, or **Command Prompt** and run:
```powershell
irm https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/install.ps1 | iex
# Or via custom domain:
# irm https://gitsetu.bhaskarjha.dev/install.ps1 | iex
```

> [!IMPORTANT]
> **Windows Prerequisite:** GitSetu requires **Git for Windows** (which provides standard `git.exe` and `bash.exe`).
> If you do not have Git installed yet, run:
> ```powershell
> winget install Git.Git
> ```
> or download from [git-scm.com/download/win](https://git-scm.com/download/win).

> [!TIP]
> **Zero Friction on Windows:** The PowerShell installer automatically configures native `gitsetu.cmd` and `gitsetu.ps1` command shims and adds `%LOCALAPPDATA%\gitsetu\bin` directly to your Windows User `PATH`. You can run `gitsetu` or `git setu` immediately in PowerShell, Command Prompt, or VS Code without opening Git Bash!

### Windows (via Git Bash)
If you prefer working exclusively inside Git Bash:
```bash
curl -sL https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/install.sh | bash
```

---

## 2. Package Managers & Ecosystem Wrappers

### Node.js — npm & npx
Run instantly without global installation, or install globally across any OS:
```bash
# Instant one-shot setup (no installation needed)
npx gitsetu setup --auto

# Or global install
npm install -g gitsetu
```

### Windows — Microsoft WinGet
Install via the official Windows Package Manager:
```powershell
# Official Microsoft Package Identifier (Publisher.PackageName)
winget install BhaskarJha.GitSetu

# Or once indexed in local manifests:
winget install GitSetu
```

> [!NOTE]
> `BhaskarJha.GitSetu` is the canonical, collision-proof Package Identifier in Microsoft's official `winget-pkgs` repository.

### Windows — Scoop
Install via Scoop bucket:
```powershell
scoop bucket add gitsetu https://github.com/bhaskarjha-dev/scoop-gitsetu
scoop install gitsetu
```

### macOS & Linux — Homebrew
Install via Homebrew tap:
```bash
brew tap bhaskarjha-dev/tap
brew install gitsetu
```

### Arch Linux — AUR
Install via your preferred AUR helper:
```bash
yay -S gitsetu
# or
paru -S gitsetu
```

### Nix & NixOS — Nix Flake
Execute or install hermetically via Nix Flakes:
```bash
# Run directly without polluting system state
nix run github:bhaskarjha-dev/gitsetu -- setup --auto

# Or install to your user environment
nix profile install github:bhaskarjha-dev/gitsetu
```

### GitHub CLI Extension
Integrate directly into `gh` CLI:
```bash
gh extension install bhaskarjha-dev/gh-gitsetu
gh gitsetu setup
```

---

## 3. Standalone Monolith (Direct Curl)

If you need a single, zero-dependency executable without cloning the repository or downloading extra folders:

```bash
mkdir -p ~/.local/bin
curl -sL https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/dist/gitsetu -o ~/.local/bin/gitsetu
chmod +x ~/.local/bin/gitsetu
```

---

## 4. Manual Installation (From Source)

If your machine is behind an air-gapped firewall:

```bash
# 1. Clone the repository
git clone https://github.com/bhaskarjha-dev/gitsetu.git ~/.local/share/gitsetu

# 2. Symlink or copy the binary
mkdir -p ~/.local/bin
ln -sf ~/.local/share/gitsetu/gitsetu ~/.local/bin/gitsetu
ln -sf ~/.local/share/gitsetu/gitsetu ~/.local/bin/git-setu

# 3. Ensure ~/.local/bin is in your PATH
export PATH="$HOME/.local/bin:$PATH"
```

---

## Post-Installation First Steps

Once installed, verify that GitSetu is available:
```bash
gitsetu --version
# Outputs: gitsetu v1.0.0
```

### Instant 1-Second Setup
Bootstrap all detected identities without prompts:
```bash
gitsetu setup --auto
```

### Interactive Dashboard Setup
Review and tweak your identities visually:
```bash
gitsetu setup
# Or use the native Git alias:
git setu setup
```

---

## Testing in Windows Sandbox

If you are on Windows and want to test GitSetu safely in an isolated, disposable virtual machine without touching your personal configuration, clone the repository and launch the sandbox harness:
```cmd
.\sandbox\launch_sandbox.bat
```

---

## Upgrading

GitSetu includes an atomic self-updater:
```bash
gitsetu update
```

Or upgrade through your package manager:
```bash
npm update -g gitsetu         # npm
winget upgrade BhaskarJha.GitSetu # WinGet
scoop update gitsetu          # Scoop
brew upgrade gitsetu          # Homebrew
yay -Syu gitsetu              # Arch AUR
```

---

## Complete Uninstallation

Because GitSetu integrates cleanly into your global `~/.gitconfig` and OpenSSH configuration files, **always run teardown first** before deleting files:

```bash
gitsetu teardown --deep
```

### Removing Binaries & Files

- **macOS / Linux:**
  ```bash
  curl -sL https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/uninstall.sh | bash
  ```
- **Windows (PowerShell):**
  ```powershell
  irm https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/uninstall.ps1 | iex
  ```
- **npm:**
  ```bash
  npm uninstall -g gitsetu
  ```
- **WinGet:**
  ```powershell
  winget uninstall BhaskarJha.GitSetu
  ```
- **Homebrew:**
  ```bash
  brew uninstall gitsetu
  ```
- **Scoop:**
  ```powershell
  scoop uninstall gitsetu
  ```
- **GitHub CLI:**
  ```bash
  gh extension remove gh-gitsetu
  ```


--- END OF FILE: getting-started/installation.md ---

--- START OF FILE: getting-started/introduction.md ---

---
title: "Getting Started"
description: "Onboarding guide covering prerequisites, system requirements, and foundational GitSetu setup."
category: "getting-started"
slug: "getting-started/introduction"
---
# Introduction

**The bridge between your identities and your repositories.**

GitSetu is a complete, zero-dependency pipeline that instantly generates your SSH keys, hardware signatures (FIDO2), and Git configs within a Zero-Trust architecture, then automatically switches them based on your directory. 

One setup. Automatic forever.

## Why GitSetu?

If you work across multiple organizations, freelance clients, or maintain personal open-source projects, you've likely experienced the pain of Git identity management.

| Problem | What happens | GitSetu fix |
|---------|-------------|-------------|
| 🔴 **Wrong author commits** | You push a freelance project and your work email shows up in the log | Directory-scoped `includeIf` auto-switches identity |
| 🔴 **SSH key collisions** | One SSH key for three GitHub accounts — pushes fail silently | Dedicated ED25519 keypair per profile |
| 🔴 **Corporate firewall blocks SSH** | Port 22 blocked — PATs get mixed between accounts, 403 errors | Per-profile credential broker via OS keychain & Windows Credential Manager |
| 🔴 **Forgot to switch identity** | Commit lands with the wrong email — can't rewrite public history | Pre-commit guard blocks the commit before it happens |
| 🔴 **Manual directory setup** | Missing workspace directory causes routing or clone errors | Auto-creates workspace directories (`mkdir -p`) on registration |
| 🔴 **Manual global config** | Edit `~/.gitconfig` before every context switch, then forget | One-time setup, automatic forever |
| 🔴 **Tool rot & dependency hell** | Every solution requires Node, Python, or Go. They break when runtimes update. | Pure Bash 3.2. Zero dependencies. Native auto-updater. |

GitSetu provisions a complete Git identity infrastructure from scratch. No manual config editing, no memorizing SSH aliases, no dependencies.


--- END OF FILE: getting-started/introduction.md ---

--- START OF FILE: getting-started/quickstart.md ---

---
title: "Quickstart"
description: "Fast-track tutorial to configure your personal and work Git profiles in under three minutes."
category: "getting-started"
slug: "getting-started/quickstart"
---
# Quickstart

Get your Git identities routed automatically in **four simple steps**.

---

## 1. Provision your Identities

Run the interactive setup wizard. It will ask for your profile name, email, and the root directory for this identity.

```bash
gitsetu setup
```

*Example: Create profile "work" with `dev@company.com` and `~/work`.*
*Example: Create profile "personal" with `me@gmail.com` and `~/personal`.*

The wizard will automatically:
1. Generate an ED25519 SSH keypair specific to this profile.
2. Inject a Zero-Trust `Include` directive into your `~/.ssh/config`.
3. Create a managed block in your `~/.gitconfig` using the `includeIf` conditional.
4. Automatically create the workspace directory (`mkdir -p`) if it does not already exist.

---

## 2. Authenticate with your Provider

GitSetu has created your keys and configurations, but your Git provider (GitHub, GitLab) doesn't know about them yet. **Choose your authentication method below:**

### If you clone using SSH (`git@github.com:...`)
You **must** upload your newly generated public key to your provider, otherwise Git will throw a `Permission denied (publickey)` error when you try to clone.

1. Output your new public key to the terminal:
   ```bash
   cat ~/.ssh/id_ed25519_<profile>.pub
   ```
   *(Replace `<profile>` with the name you used in Step 1, e.g., `id_ed25519_work.pub`)*
2. Copy the entire output string and paste it into your [GitHub SSH Settings](https://github.com/settings/ssh/new).

### If you clone using HTTPS (`https://github.com/...`)
If you rely on Personal Access Tokens (PATs) instead of SSH keys, you must securely bind your token to your profile so you aren't prompted for a password on every push.

1. Provision or update credentials:
   You can provide PATs during the interactive `gitsetu setup` wizard, register profiles with credentials via `gitsetu profile add <label> --email=<email> ...`, or pipe credentials into the broker:
   ```bash
   printf "protocol=https\nhost=github.com\nusername=YOUR_USERNAME\npassword=YOUR_PAT\n" | gitsetu credential store
   ```
2. On Windows, GitSetu integrates directly with Windows Credential Manager (`credential.helper = manager` via DPAPI/GCM). On macOS and Linux, it securely delegates to the OS keychain or isolated fallback storage (`~/.config/gitsetu/.tokens` with `chmod 600`).

---

## 3. Verify the State

Before starting work, verify that GitSetu has successfully provisioned your profiles and the infrastructure is sound.

```bash
$ gitsetu status
  work       dev@company.com    ~/work      ✓ active
  personal   me@gmail.com       ~/personal
  freelance  ak@freelance.io    ~/clients
```

---

## 4. The Magic: Just `cd` and work

GitSetu does the rest. It natively intercepts directory changes and switches your Git email, SSH key, and Credentials completely transparently. **You do not need to run any commands when switching projects.**

```text
$ cd ~/work/my-api && git commit -m "fix: auth bug"
Author: Aditya Kumar <dev@company.com> ← correct, automatically
```

> [!TIP]
> **Global Fallback:** By default, GitSetu enforces `useConfigOnly = true` — commits outside a mapped directory are blocked to prevent identity leakage. If you register a profile with an unmapped directory (`""`), GitSetu provisions it as your `[Global Fallback]` identity before conditional `[includeIf]` rules, ensuring standard commits succeed across unmapped paths while preserving strict directory isolation.


--- END OF FILE: getting-started/quickstart.md ---

--- START OF FILE: guides/hardware-keys.md ---

---
title: "Hardware Keys (FIDO2)"
description: "Configuration guide for FIDO2/WebAuthn hardware security keys and resident SSH credentials."
category: "guides"
slug: "guides/hardware-keys"
---
# Hardware Keys (FIDO2 / YubiKey)

**Bootstrapping highly secure, tamper-resistant SSH authentication keys backed directly by hardware tokens.**

GitSetu natively supports provisioning FIDO2-backed resident SSH keys (`ed25519-sk`). This operational paradigm ensures that private cryptographic signatures are generated and held strictly inside external physical security keys (e.g., YubiKey 5 Series), completely protecting key material from extraction even if your local host filesystem is compromised.

---

## Technical Prerequisites

To execute hardware-backed setup paths successfully, verify your local system environments meet standard cryptographic support targets:
- **OpenSSH Version:** Core OpenSSH binary `v8.2` or higher (introduced natively in early 2020).
- **Physical Token:** A dedicated FIDO2/WebAuthn compliant hardware security device.
- **Host Drivers:** Client integration libraries (`libfido2`) active on your operational OS layer.

---

## Provisioning Workflow

When initializing a new workspace configuration profile via the interactive setup wizard (`gitsetu setup`), the system scans your local compilation environment to verify hardware crypto capability.

If validated successfully, the interface presents native hardware key generation pathways inline:

```text
What type of SSH key do you want to generate?
1) ED25519    (Standard Software Keypair, Optimized Curve)
2) ED25519-SK (FIDO2 / YubiKey Hardware Security Token)
```

### The Generation Intercept

1. Select option **`2`**.
2. Connect your physical token directly into an available host USB interface.
3. The terminal halts execution mid-flight. **Physically tap the capacitive contact** on your hardware key to confirm user presence.
4. GitSetu compiles an isolated host pointer layout (`~/.ssh/id_ed25519_sk_<profile>`) containing reference hooks linking directly to your physical token.
5. The generated public key payload streams directly out for integration, while configuration blocks automatically pivot to leverage your OpenSSH zero-trust bounds.

---

## Runtime Verification Mechanics

When executing code pushes or fetching protected upstream branches over SSH, OpenSSH reads the localized key hook pointer and streams an evaluation request to the attached physical device.

```text
$ git push origin main
Confirm user presence for key ED25519-SK...
```

Your terminal session pauses automatically. You must **physically touch the hardware key** to complete the handshake negotiation. If an adversarial actor steals your laptop or intercepts remote terminal environments, they remain structurally incapable of pushing commits because the cryptographic operation requires explicit physical proximity verification.

---

## Recovery & Redundancy Guard Rails

> [!WARNING]
> **Hardware Loss Risk:** Because the cryptographic private key resides strictly inside the secure element of your physical device, losing the physical token permanently destroys access to the SSH keypair. Always register redundant access paths (such as secondary hardware keys or restricted Personal Access Tokens) within your upstream provider configuration settings.


--- END OF FILE: guides/hardware-keys.md ---

--- START OF FILE: guides/shell-prompt.md ---

---
title: "Shell Prompt Integration"
description: "Dynamic prompt modules for Bash, Zsh, Starship, and Fish displaying the active Git identity."
category: "guides"
slug: "guides/shell-prompt"
---
# Shell Prompt Integration

**Sub-millisecond runtime execution surfacing your active Git identity directly inside your terminal shell.**

Committing code using the wrong author context often occurs because developers lack instant visual feedback regarding which identity profile owns their current terminal workspace directory.

GitSetu includes a specialized, high-speed **Prompt Engine** designed specifically to expose your active workspace context natively inside your command prompt (`$PS1`), Oh-My-Zsh themes, and cross-shell tools like Starship.

---

## The Performance Paradigm

Rendering logic inside terminal prompt structures executes every single time you hit `Enter`. If a prompt integration spawns external binary runtimes, executes multi-stage subprocesses, or queries network layers, shell interactivity grinds to a halt.

GitSetu's `prompt` subcommand is engineered with absolute performance constraints:
- **Pure Native Bash Parsing:** Scans pre-compiled configuration routing links natively using direct memory offsets.
- **Zero Subshell Spawning:** Bypasses costly `fork()` syscalls entirely during state reads.
- **Sub-2ms Execution:** Total context identification completes consistently in **`< 2 milliseconds`**, keeping your command-line workflow blisteringly responsive.
- **Longest-Prefix Match Routing:** Seamlessly handles nested folders (e.g. `~/work/clients/acme/` vs `~/work/`) by prioritizing the most specific directory match.
- **Cross-Platform Case-Insensitivity:** Automatically normalizes path casing on Windows (NTFS) and macOS to prevent prompt desync between uppercase and lowercase path representations.

---

## Integration Setup

### Standard Bash (`~/.bashrc`)
To prepend the active profile identifier directly to your terminal prompt line, append the following snippet to your shell configuration profile:

```bash
# GitSetu Native Shell Prompt Integration
gitsetu_ps1() {
    local profile
    # Rapidly extract current profile context silently
    profile=$(gitsetu prompt 2>/dev/null)
    if [ -n "$profile" ]; then
        echo "[$profile] "
    fi
}

# Update PS1 command rendering chain
PS1='$(gitsetu_ps1)'$PS1
```

### Zsh / Oh-My-Zsh (`~/.zshrc`)
Integrate context flags gracefully inside custom Zsh layout strings:

```zsh
# Enable command substitution within Zsh prompt evaluation
setopt PROMPT_SUBST

gitsetu_prompt_info() {
    local profile=$(gitsetu prompt 2>/dev/null)
    [[ -n "$profile" ]] && echo "%{$fg[cyan]%}[$profile]%{$reset_color%} "
}

# Inject cleanly ahead of standard prompt strings
PROMPT='$(gitsetu_prompt_info)'$PROMPT
```

### Starship Cross-Shell Prompt (`~/.config/starship.toml`)
For developers leveraging the popular high-speed Starship engine, provision a dedicated custom module block:

```toml
[custom.gitsetu]
command = "gitsetu prompt"
when = "gitsetu prompt >/dev/null 2>&1"
format = "via [$output]($style) "
style = "bold cyan"
```

---

## Output Behavior

When traversing across folders, visual updates render instantly:

```text
# Inside unmapped general directories
~ ❯ cd ~/work/api-gateway
# Context updates instantly mid-flight
[work] ~/work/api-gateway ❯ 
```


--- END OF FILE: guides/shell-prompt.md ---

--- START OF FILE: guides/vault-backups.md ---

---
title: "Vault Backups"
description: "Encrypted profile backup, restoration, and cryptographic verification procedures."
category: "guides"
slug: "guides/vault-backups"
---
# Vault Backups & Restoration

**Bare-metal state extraction via OpenSSL encrypted archival bounds.**

Software developers cycle hardware instances regularly. Provisioning completely new cryptographic identity materials across entirely new OS bounds and subsequently registering those newly generated public keys across disparate upstream Git hosting providers can introduce hours of critical downtime.

GitSetu resolves this operational friction natively by providing high-speed encrypted vault extraction tools to migrate your complete structural state securely between machines.

---

## Vault Compilation (Backup)

To generate an atomic, portable extraction payload of your current configuration baseline, trigger the explicit backup command:

```bash
gitsetu backup
```

### Extracted Architecture Scope
The internal snapshot utility perfectly bundles the following active path domains:
- **Master Registry Maps:** Core configuration indexing (`~/.config/gitsetu/profiles.conf`).
- **Profile Layout Directives:** All dynamically mapped individual configuration override bounds (`~/.config/gitsetu/profiles/*.gitconfig`).
- **Zero-Trust Host Directives:** The active OpenSSH network translation paths (`~/.config/gitsetu/profiles/ssh_config`).
- **Private Cryptographic Keys:** All actively generated native software key bounds linked exclusively to existing GitSetu profile environments (`~/.ssh/id_*`).

### OpenSSL AES-256 Cryptography
Because the generated compressed target payload natively includes highly sensitive cryptographic private key components, GitSetu mandates strict encryption protocols. 

The backup routine natively leverages standard `openssl` binaries accessible on your runtime OS, encrypting the compiled target `tar` payload synchronously utilizing robust **AES-256-CBC** cryptographic blocks keyed heavily via standard `-pbkdf2` derivation loops.

> [!CAUTION]
> **Data Loss Warning:** During the initial execution phase, GitSetu securely prompts you to declare a master encryption password string. If you forget or lose this precise passphrase, your encrypted target vault file remains mathematically irretrievable. The structural data inside the vault cannot be extracted.

Upon successful completion, execution terminates cleanly yielding a highly portable encoded archive block named structurally as `gitsetu_vault_YYYYMMDD_HHMMSS.tar.gz.enc`. Store this block heavily isolated inside protected password managers, heavily constrained cloud bounds, or offline cold storage keys.

---

## Architecture Reconstruction (Restore)

After migrating your terminal execution environments to new bare-metal targets or initializing fresh OS bounds, simply initialize GitSetu strictly via the baseline [Installation](/docs/getting-started/installation) pathway first.

Instead of calling the standard interactive setup wizard, explicitly execute the targeted payload reconstruction subcommand passing your target encrypted vault file payload:

```bash
gitsetu restore /path/to/gitsetu_vault_YYYYMMDD_HHMMSS.tar.gz.enc
```

### The Reconstruction Process
Execution requires providing your pre-declared encryption passphrase string inline. 
Upon successful decryption validation, GitSetu dynamically decomposes the `tar` payload structure into memory, accurately translating key path attributes directly into the local target `~/.ssh/` filesystem structure using aggressively constrained file permissions. The internal compiler reconstructs your global `~/.gitconfig` conditional routing mappings and injects the baseline OpenSSH `Include` directive flawlessly.

The entire environment reconstruction operation completes seamlessly in single-digit seconds, fully re-establishing your multi-profile capability pipeline instantaneously.


--- END OF FILE: guides/vault-backups.md ---

--- START OF FILE: guides/wsl-integration.md ---

---
title: "WSL Integration"
description: "Seamless Windows Subsystem for Linux (WSL) interoperability with Windows credential managers."
category: "guides"
slug: "guides/wsl-integration"
---
# WSL Integration

**Seamless identity and file-path harmonization across Windows Subsystem for Linux environments.**

Because GitSetu is compiled strictly utilizing pure, POSIX-compliant Bash 3.2, it achieves absolute native execution compatibility across all Windows Subsystem for Linux (WSL) environments (Ubuntu, Debian, Alpine, etc.). The tool requires zero Windows-specific `.exe` dependencies, operating entirely decoupled from standard host virtualization layers.

---

## Installation Pathways

Inside your WSL terminal execution layer, initialize the standard Linux bootstrapping script exactly as you would on bare-metal hardware:

```bash
curl -sL https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/install.sh | bash
```

---

## Cross-Boundary File Harmonization

When generating isolated identity profiles inside WSL environments, developers frequently bridge Linux operational boundaries into native Windows disk mounts.

### Path Evaluation Mechanics
Always supply absolute Linux path strings targeting your target repositories (e.g., `~/projects/work` or `/mnt/c/Users/Name/work`).

Because GitSetu compiles paths directly into Git's native `includeIf` conditional boundaries, Git interprets the Linux-structured paths seamlessly during runtime evaluation. Execution matches reliably whether target repositories exist on isolated WSL root drives or explicitly mounted back across to primary Windows `C:\` bounds.

---

## HTTPS Credential Brokering in WSL

The primary operational complexity introduced by headless WSL containers centers around mapping HTTPS Personal Access Tokens (PATs) securely, as standard Linux secret layers (e.g., `secret-tool`) typically remain unavailable in CLI-only runtimes.

### Native Vault Fallbacks
When you store an active profile token inside a headless WSL instance lacking D-Bus secret integrations (via `gitsetu credential store` or `gitsetu setup`), GitSetu dynamically switches execution modes.

It automatically provisions an isolated, restricted permissions payload vault file located directly at `~/.config/gitsetu/.tokens`. The directory and file enforce strict POSIX permissions (`700` directory, `600` file) to guarantee containment.

### Microsoft Git Credential Manager (GCM) Interoperability
If your local environment utilizes Microsoft's cross-platform [Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager) to securely proxy WSL Git operations back into your native Windows Credential Store, GitSetu respects the configuration gracefully.

> [!WARNING]
> **GCM Identity Collisions:** Standard GCM pipelines struggle fundamentally to partition tokens bound to identical overlapping base hostnames (e.g., mapping distinct personal and corporate tokens concurrently to `github.com`). If you absolutely require Port 443 HTTPS multi-tenant cloning capabilities, we explicitly recommend utilizing GitSetu's native built-in fallback vault architecture.


--- END OF FILE: guides/wsl-integration.md ---

--- START OF FILE: index.md ---

---
title: "Introduction"
description: "Zero-dependency Git multi-identity orchestration and automated SSH profile switching for modern developer workflows."
category: "overview"
slug: "index"
---
# Introduction to GitSetu

**The enterprise Zero-Dependency orchestration engine for dynamic Git identity and credential isolation.**

GitSetu completely reimagines developer identity security. Operating purely as a localized configuration compiler, it completely eliminates the human error associated with managing multiple identities across isolated workspaces, enterprise repositories, and open-source contributions. 

By unifying automated multi-key generation, native credential helper integration, and hardware signature validation into a single workflow, GitSetu establishes an impenetrable Zero-Trust boundary around your local source code environments.

---

## The Identity Crisis: What We Solve

Modern developer environments are highly fragmented. Context-switching between distinct organizations creates massive risk surfaces that traditional Git setups simply fail to protect against.

| The Operational Vulnerability | Typical Failure Mode | The GitSetu Automated Engine |
| :--- | :--- | :--- |
| 🔴 **Corporate Identity Leaks** | Committing private proprietary code using a personal email address or public alias. | **Directory-Scoped `includeIf` Interception:** Dynamically swaps active user configuration based on absolute working paths mid-flight. |
| 🔴 **Silent Authentication Collisions** | Single SSH keys loaded globally against overlapping multi-tenant remote hosts (e.g., `github.com`). | **Dedicated Zero-Trust Key generation:** Bootstraps pure, isolated `ed25519` keypairs namespaced exactly to each workspace profile. |
| 🔴 **Cross-Profile PAT Pollution** | HTTPS pull/push streams blindly pulling cached global tokens from OS credentials, returning `HTTP 403 Forbidden`. | **Native Namespaced Credential Broker:** Wraps authentication layers to securely proxy PATs directly via `security` / `secret-tool` keychains. |
| 🔴 **Untracked Historical Config Drift** | Manual one-off edits to global `.gitconfig` files drifting out of compliance over time. | **Idempotent Managed Blocks Protocol:** Stateful compiler that surgically orchestrates local config structures without overwriting global blocks. |
| 🔴 **Pre-Flight Failure Vulnerability** | Forgetting to execute environment prep scripts before pushing code to protected branches. | **Fail-Closed Identity Guard:** Enforces inline verification during pre-commit phases, aborting instantly if config integrity diverges. |

---

## Architectural Distinctions

### Indistinguishable from Magic: The Native Clone
Competitor tools require developers to memorize custom SSH host aliases (e.g., `git clone git@github-work:org/repo.git`). GitSetu rejects this sub-optimal design pattern. 

By injecting customized `core.sshCommand` configurations conditionally during path evaluation, GitSetu natively intercepts connections *before* outbound sockets initialize. Developers clone, pull, and push normally (`git clone git@github.com:org/repo.git`), while GitSetu silently attaches the exact keypair required by the target directory.

### Absolute Zero Dependencies
Enterprise compliance frameworks frequently prohibit downloading untrusted runtime dependencies onto production machines or secure CI/CD runners. 

GitSetu is written purely in hardened, POSIX-compliant **Bash 3.2**. It requires no Go binaries, no Node runtime engines, no Python virtual environments, and no Rust toolchains. It relies strictly on `bash`, `git`, and `ssh-keygen`—core standard binaries guaranteed to exist natively on every developer workstation and CI environment.

### Fail-Closed Zero-Trust Guard Rails
GitSetu operates on the principle of maximum defensiveness. With options like `useConfigOnly = true` baked into its managed layout protocols, Git natively raises fatal execution errors inside unmapped folders, ensuring code cannot leave your machine unless an authenticated identity profile has explicitly claimed authority over that directory path.

---

## Getting Started

Ready to eradicate repository configuration friction permanently?
- **[Install GitSetu](/docs/getting-started/installation)** — Bootstrap directly in your terminal.
- **[Quickstart Guide](/docs/getting-started/quickstart)** — Provision your entire profile architecture from scratch in under 60 seconds.


--- END OF FILE: index.md ---

--- START OF FILE: overview/architecture.md ---

---
title: "Architecture"
description: "Internal mechanics, modular compilation patterns, and zero-trust execution flows of GitSetu."
category: "overview"
slug: "overview/architecture"
---
# System Architecture

**A comprehensive deep dive into the internal mechanics, modular compilation patterns, and zero-trust execution flows of GitSetu.**

GitSetu achieves robust multi-identity orchestration without relying on long-running daemons or binary runtimes. Operating purely as a **localized configuration compiler**, it statefully compiles native Git and OpenSSH structures, delegating continuous runtime evaluation directly to standard OS routing mechanisms.

---

## The Compilation Paradigm

Unlike traditional switchers that spawn watcher processes or intercept shell execution paths via wrapper functions, GitSetu executes on demand. 

```
[ Developer Input ] 
       │
       ▼
[ gitsetu setup ] ──(Stateful CLI Wizard)
       │
       ▼
[ Atomic Managed Blocks ] ──► ~/.gitconfig (includeIf routing tables)
                            └──► ~/.ssh/config (OpenSSH Include pivot)
       │
       ▼
[ Complete Process Teardown ] (Zero residual runtime daemons)
```

When triggered, GitSetu reads your profile specifications, injects precisely formatted conditional rules into your persistent configuration stores, and exits entirely. Git and OpenSSH handle runtime evaluation natively.

---

## Subsystem Mechanics

### 1. Global Identity Routing (`~/.gitconfig`)
GitSetu establishes a highly secure routing framework by deploying atomic, demarcated blocks labeled with custom signatures (e.g., `[gitsetu:managed:start]`).

Inside these managed bounds, GitSetu maps local folders to isolated target files using Git's built-in `includeIf` condition:
```ini
# Linux / macOS:
[includeIf "gitdir:~/work/"]
    path = ~/.config/gitsetu/profiles/work.gitconfig

# Windows (Case-Insensitive & Canonical C:/ path):
[includeIf "gitdir/i:C:/Users/username/work/"]
    path = ~/.config/gitsetu/profiles/work.gitconfig
```
When your active terminal session traverses into any sub-path of your workspace, Git natively intercepts the operation, seamlessly applying your professional email and custom execution parameters inline. On Windows, the `gitdir/i:` keyword guarantees case-insensitive path evaluation across all shells.

### 2. OpenSSH `Include` Integration
Mutating global `~/.ssh/config` files inline violates zero-trust principles and risks catastrophic corruption of existing host parameters. 

GitSetu resolves this by leveraging OpenSSH 7.3+'s native `Include` directive. During initial setup, GitSetu prepends a single portable routing link to the absolute top of your configuration file:
```ini
Include ~/.config/gitsetu/profiles/ssh_config
```
All distinct host configurations, custom identity file pointers (`IdentityFile ~/.ssh/id_ed25519_work`), and strict verification flags (`IdentitiesOnly yes`) are exclusively orchestrated inside GitSetu's isolated layout layer, guaranteeing absolute sandboxing across Linux, macOS, and native Windows OpenSSH (`ssh.exe`).

### 3. Fail-Closed Identity Guard (Pre-Commit)
To eliminate multi-state identity drift (e.g., configuring GitSetu but accidentally setting local `.git/config` overrides manually), GitSetu deploys a lightweight global hooks boundary (`core.hooksPath`).

1. **Commit Interception:** The global hook triggers the moment `git commit` executes.
2. **Registry Verification:** Rapidly loads the master profile state from `~/.config/gitsetu/profiles.conf`.
3. **Identity Verification:** Compares the expected profile email address for the local file path against the active runtime string returned by `git config user.email`.
4. **Execution Decision:** If values match, execution proceeds. If values diverge, it raises an instant fatal termination (`exit 1`), blocking unauthorized code from hitting remote branches.

### 4. Namespaced Credential Brokering
When authenticating over HTTPS, standard credential managers frequently mix Personal Access Tokens (PATs) for identical hostnames. 

GitSetu injects itself as a proxy credential helper (`[credential] helper = "/path/to/gitsetu credential"`). When upstream syncs fire, GitSetu intercepts the authentication pipeline, evaluates active directory context, and requests heavily namespaced tokens from the underlying operating system (e.g., `gitsetu:work:github.com`), completely stopping cross-tenant authentication cross-talk.

---

## Zero-Trust Architecture & Concurrency Boundaries

To ensure absolute resilience under parallel builds, cross-platform environments, or automated Continuous Integration:
- **Atomic File Hot-Swaps:** All global configuration mutations write out to isolated temp directory contexts (`$TMPDIR/..._$$_${RANDOM}`) before executing immediate atomic renames (`mv`), eliminating mid-write interruption vectors.
- **POSIX Lock Reaping:** Subsystem routines generate dedicated execution lock blocks via `mkdir` primitives (`profiles.lock`) with PID verification to safely process concurrent requests without race conditions and auto-reap stale locks.
- **Unified Global Traps:** Comprehensive signal traps (`EXIT / SIGINT / SIGTERM`) guarantee orphaned states, transient arrays, and partial file descriptors are cleanly collected even if execution panics.
- **Automatic Workspace Directory Provisioning:** Automatically provisions missing workspace directories via `mkdir -p` when applying blueprints during setup or CLI profile addition.
- **Longest-Prefix Match Routing:** Evaluates nested directory structures deterministically, prioritizing the deepest matching directory boundary across identity routing, pre-commit guards, and prompt lookups.
- **Multi-Profile Persistence & Re-hydration:** Re-running setup safely re-hydrates existing profiles from `profiles.conf`, allowing non-destructive iterative updates.
- **Safe SSH Command Quoting:** Enforces escaped double-quoting around SSH key paths containing spaces in `core.sshCommand` and `GIT_SSH_COMMAND`.
- **Windows Sandbox Test Harness:** Completely disposable, host-isolated validation container (`sandbox/`) executing all 36 regression & empirical test suites and multi-profile simulations without touching the host machine.

---

## Core Library Module Map

GitSetu loads distinct library dependencies dynamically during runtime compilation:

| Module Base | Core Responsibility Scope |
| :--- | :--- |
| **`core.sh`** | Version, XDG paths, 9 parallel state arrays, `load_profiles()`, `remove_profile_at_index()`. |
| **`platform.sh`** | OS detection (`detect_os`), path normalization, gitdir keyword selection. |
| **`ui.sh`** | Terminal output (`print_success/error`), interactive prompts, setup banner. |
| **`validate.sh`** | Input validation: emails, GitHub noreply formats, labels, path overlap detection. |
| **`setup.sh`** | Interactive terminal layout generation and POSIX execution lock reapers. |
| **`gitconfig.sh`** | `includeIf` block rendering, configuration bounds validation, and base profile writing. |
| **`ssh.sh`** | Dedicated cryptographic key bootstrapping and isolated OpenSSH `Include` proxy writing. |
| **`guard.sh`** | Pre-commit hook deployment and global hook virtualization handling. |
| **`doctor.sh`** | Multi-point environment diagnostics and configuration drift discovery. |
| **`verify.sh`** | Infrastructure verification: SSH key existence/permissions, gitconfig integrity. |
| **`backup.sh`** | File-level timestamped backups, OpenSSL encrypted vault export/import. |
| **`teardown.sh`** | Profile removal, managed block cleanup, deep local-repo identity stripping. |
| **`discovery.sh`** | Auto-discovery: SSH key email extraction, gitconfig identity parsing, workspace detection. |
| **`keychain.sh`** | Cross-platform credential broker routing to macOS Keychain and Linux Secret Service. |
| **`completion.sh`** | TAB completion for Bash/Zsh: subcommands and profile name completion. |


--- END OF FILE: overview/architecture.md ---

--- START OF FILE: overview/comparisons.md ---

---
title: "Ecosystem Comparisons"
description: "Comparative evaluation of GitSetu versus manual SSH configs, direnv, and alternative Git identity managers."
category: "overview"
slug: "overview/comparisons"
---
# Git Identity Tools: Comprehensive Comparison

**An authoritative, deep-dive competitive matrix evaluating multi-identity Git managers across features, architecture, safety, and developer experience.**

Managing multiple directory-scoped Git identities securely is a foundational challenge. To help engineering organizations and security managers evaluate their options, this document provides an objective, side-by-side comparison of the six leading approaches to Git identity switching as of **September 2026 (v1.0.0 GA)**.

---

## Overall Composite Scores

Scores reflect a balanced evaluation of feature breadth, zero-trust reliability, user experience, community presence, and portability constraints.

| Tool | Approach / Runtime | Composite Score | Feature Breadth | Ease of Use | Reliability | Community Stars | Portability |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| 🏆 **GitSetu** | **Zero-Dependency Bash Core** | **86 / 100** | **95%** | **80%** | **90%** | **★ 0** | **75%** |
| **gitego** | Go Binary Switcher | **76 / 100** | 75% | 85% | 78% | ★ ~20 | 90% |
| **karn** | Mature YAML Switcher (Go) | **68 / 100** | 40% | 85% | 85% | ★ 306 | 90% |
| **gitch** | Feature-Rich TUI (Go) | **72 / 100** | 88% | 72% | 55% | ★ 5 | 90% |
| **gh-switcher** | GitHub-Focused CLI (Go) | **60 / 100** | 60% | 72% | 50% | ★ 3 | 85% |
| **Manual DIY** | Hand-Rolled `.ssh/config` | **54 / 100** | 100% | 20% | 80% | N/A | 100% |

---

## Detailed Feature Matrix

| Feature Capability | GitSetu | gitego | karn | gitch | gh-switch | Manual DIY |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **Identity Switching Mechanics** | | | | | | |
| Directory auto-switch (`cd` trigger) | ✓ | ✓ | ✓ | ✓ | ✓ | ~ |
| Native Git `includeIf` integration | ✓ | ✓ | ✓ | ✓ | ~ | ✓ |
| Deep directory path recursion | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Manual CLI profile override | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Global fallback identity safety | ✓ | ✓ | ~ | ✓ | ✓ | ✓ |
| **SSH & Cryptography Orchestration** | | | | | | |
| Automated `ed25519` key generation | ✓ | ~ | ~ | ~ | ✗ | ✗ |
| Top-level OpenSSH `Include` pivot | ✓ | ~ | ~ | ✓ | ✗ | ✓ |
| Native SSH commit signing (`gpgsign`) | ✓ | ~ | ✓ | ✓ | ✗ | ~ |
| Hardware key bootstrapping (FIDO2) | ✓ | ✗ | ✗ | ✗ | ✗ | ~ |
| Standard clone URLs (`git@github.com`) | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ |
| **HTTPS & Credential Brokering** | | | | | | |
| Namespaced PAT authentication routing | ✓ | ✓ | ~ | ✓ | ✓ | ✗ |
| OS keychain integration (`security`) | ✓ | ✓ | ~ | ✓ | ✓ | ~ |
| **Safety Guard Rails & Integrity** | | | | | | |
| Pre-commit Identity Guard (fail-closed) | ✓ | ~ | ✓ | ✓ | ✗ | ✗ |
| Idempotent managed block parsing | ✓ | ✓ | ✓ | ~ | ~ | ✗ |
| Atomic configuration writes | ✓ | ✓ | ✓ | ~ | ~ | ✓ |
| **Diagnostics & Team Operations** | | | | | | |
| Built-in `doctor` configuration scanner | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ |
| Hyper-optimized prompt integration | ✓ | ✓ | ✓ | ✓ | ✓ | ✗ |
| Encrypted state export & restoration | ✓ | ~ | ✗ | ✗ | ✗ | ✗ |
| **Technical Footprint** | | | | | | |
| Runtime dependency requirements | **None** | Go | Go | Go | Go | None |
| Active maintenance lifecycle | **High** | High | Stale | High | Low | N/A |

*(✓ = fully supported, ~ = partial / manual intervention required, ✗ = unsupported)*

---

## Strategic Deep Dive: Best For Each Use Case

### 🏆 Best Overall: GitSetu
GitSetu covers the widest operational scope end-to-end. It is the only platform evaluated that seamlessly combines **automated SSH key generation**, directory-scoped multi-key routing, native OS credential brokering, fail-closed pre-commit guard enforcement, encrypted state backups, and interactive diagnostics into a single, cohesive engine. 

**The Trade-off:** As a new entrant (★ 0 stars), GitSetu has a smaller community footprint than mature Go-based tools. However, it ships with the widest distribution coverage at launch: npm, Homebrew, Scoop, WinGet, AUR, Nix, GitHub CLI extension, and native shell installers for both POSIX and PowerShell.

### 🪟 Windows Environments
While tools like `gitego` compile native `.exe` binaries, GitSetu provides first-class, production-grade Windows support under Git Bash with native integration across PowerShell, CMD, Windows Terminal, and VS Code. GitSetu automatically compiles canonical Windows paths (`C:/path`), configures case-insensitive `gitdir/i:` directives, binds natively to **Windows Credential Manager (GCM)** via DPAPI, and provides a host-isolated **Windows Sandbox Test Harness** (`sandbox/`) for zero-risk verification.

### 🏛️ Best for Battle-Tested Simplicity: `karn`
With over 300+ GitHub stars and years of historical deployment stability, `karn` provides exceptionally reliable directory-to-identity switching via clean YAML definitions. 
**The Trade-off:** Extremely narrow functional footprint. It acts purely as a switcher, omitting cryptographic key bootstrapping, agent virtualization handling, and secure token isolation entirely.

### 🛡️ Most Control & Auditability: Manual DIY
Writing conditional `includeIf` directives and manually crafting namespaced `~/.ssh/config` host alias blocks provides absolute zero-black-box execution. 
**The Trade-off:** Imposes brutal operational friction. Requires developers to remember specialized remote formatting strings (`git clone git@github-work:org/repo.git`), scales poorly across enterprise developer fleets, and provides zero dynamic feedback inside the editor or terminal shell.

---

## Conclusion

If you require seamless, automated identity security across POSIX-compliant platforms (macOS, Linux, WSL) and native Windows environments with absolute zero runtime dependencies, **GitSetu stands alone as the category winner.** 

If native compiled distribution targets or integrated IDE extensions represent hard operational blockers for your team, reviewing alternative Go tools or consulting our upcoming feature milestones provides clear planning direction.


--- END OF FILE: overview/comparisons.md ---

--- START OF FILE: overview/manifesto.md ---

---
title: "Design Manifesto"
description: "Core engineering principles prioritizing zero dependencies, POSIX compliance, and atomic safety."
category: "overview"
slug: "overview/manifesto"
---
# The Design Manifesto

**The foundational principles, uncompromising constraints, and architectural philosophy driving GitSetu.**

GitSetu was engineered to solve a pervasive operational friction: managing multiple isolated Git identities across overlapping organizational bounds is universally broken. 

Standard workflows require developers to constantly toggle configuration contexts between enterprise source trees, customer delivery repositories, and personal sandboxes. The operational tooling required to maintain these environments—hand-crafting SSH host blocks, writing manual conditional logic, and diagnosing platform virtualization issues—imposes immense operational overhead and massive risk surfaces.

GitSetu exists to automate these operations out of existence permanently.

---

## Uncompromising Principles

### 1. The Magical Clone (Absolute Frictionless UX)
Traditional dual-identity approaches force developers to use non-standard clone URLs containing specialized host aliases (`git clone git@github-work:org/repo.git`). We fundamentally reject this design pattern.

GitSetu leverages directory-scoped `includeIf` conditional mapping to inject custom `core.sshCommand` parameters mid-flight during repository cloning. Developers clone, fetch, and push standard URLs exactly as they normally would (`git clone git@github.com:org/repo.git`). GitSetu intercepts the local path evaluation and dynamically routes execution through the designated cryptographic keypair. The bridging layer is entirely invisible.

### 2. Absolute Zero Runtime Dependencies
A core environment bootstrapping script that requires downloading complex package managers or language runtimes to install is fundamentally contradictory.

GitSetu is compiled strictly in hardened, POSIX-compliant **Bash 3.2**. It relies on zero external language dependencies—no Go runtimes, no Python scripts, no Node packages, and no Homebrew installations. It executes using `bash`, `git`, and `ssh-keygen` exclusively. This guarantees extreme multi-platform portability across legacy OS bounds, minimal container builds, and headless CI/CD execution environments.

### 3. Strict Idempotency & Safe Self-Healing
Blind configuration string appends frequently corrupt configuration states. 

GitSetu enforces a strict **Managed Block Protocol**. Utilizing stateful line parsing, it surgically injects or refreshes only the layout blocks it explicitly owns, leaving all user-defined global options completely untouched. It is safe to run repeatedly. Furthermore, it automatically self-heals against virtualization environments, aggressively removing CRLF line endings from VirtualBox shared mounts and injecting localized `safe.directory` rules to bypass restrictive platform ownership blocks.

### 4. Bootstrapping vs. Switching
GitSetu acts as an initial environment bootstrapper, not a manual context switcher. It does not exist to supervise custom configurations you have already manually assembled. It exists to eliminate manual assembly entirely. From a bare-metal OS setup, GitSetu securely seeds your complete identity layout architecture in under 60 seconds.

---

## The Category Moat

When developers attempt to build multi-identity solutions, they frequently rely on modern languages like Go or Rust. While these languages offer excellent execution speed, introducing a binary runtime dependency breaks the core utility of a lightweight shell setup script. 

GitSetu is highly unique because it achieved compiled-binary-level developer experience, robust concurrency isolation, and multi-point diagnostics purely using zero-dependency POSIX shell mechanics.

---

## Strict Non-Goals

To maintain absolute system reliability and maximum focus, GitSetu explicitly rejects the following product additions:
- **OAuth / Single Sign-On Orchestration:** GitSetu proxies Personal Access Tokens via native OS keychains, but intentionally avoids supervising web-based OAuth authentication loops.
- **Git Binary Wrapping:** It acts exclusively via native hooks and credential helpers, avoiding command-line alias intercepts.
- **General Workspace Dotfiles:** It strictly limits its operational domain to Git and OpenSSH identity structures.
- **Persistent Daemonization:** It operates entirely as an ephemeral configuration compiler, leaving zero lingering background listener tasks.


--- END OF FILE: overview/manifesto.md ---

--- START OF FILE: reference/cli-commands.md ---

---
title: "CLI Commands"
description: "Exhaustive CLI command reference documenting all flags, subcommands, and exit codes."
category: "reference"
slug: "reference/cli-commands"
---
# CLI Command Reference

**The complete GitSetu execution palette.**

GitSetu exposes a highly targeted, heavily validated command palette designed exclusively to interact with Git and SSH state structures. All commands are strictly idempotent.

---

## Provisioning & Setup

### `gitsetu setup [--auto] [--dry-run]`
Alias: `gitsetu init [--auto] [--dry-run]`
The primary interactive compilation wizard. Use this command to provision entirely new workspace profiles or seamlessly update existing configuration paths.
- Natively prompts for distinct Profile Labels, Developer Names, Emails, and Target Directories.
- Prompts for Zero-Trust SSH Key generation (ED25519 or FIDO2 hardware tokens).
- Safely injects atomic managed blocks directly into `~/.gitconfig` and OpenSSH configuration files.

### `gitsetu add <label> <name> <email> <dir>`
Add a new profile non-interactively via positional arguments.
- Example: `gitsetu add work "Dev Name" dev@company.com ~/work`
- Generates SSH keys, registers the profile in `profiles.conf`, and updates `~/.gitconfig` automatically.
- Automatically creates the workspace directory (`mkdir -p`) if it does not already exist.

### `gitsetu remove <label> [--force|-y]`
Remove an existing profile non-interactively or interactively.
- Safely unmounts the profile's conditional `includeIf` from `~/.gitconfig`.
- Prunes the profile configuration file `~/.config/gitsetu/profiles/<label>.gitconfig` and any orphaned configs.
- Removes profile SSH host blocks from `~/.config/gitsetu/profiles/ssh_config` and updates `profiles.conf`.
- `--force`, `-y`: Bypasses the interactive confirmation prompt for scripting and headless automation.

### `gitsetu profile <subcommand>`
Manage profiles programmatically:
- `gitsetu profile add <label> --email=<email> [--dir=<dir>] [--name=<name>] [--key=<key>] [--sign] [--provider=<provider>]`
- `gitsetu profile remove <label> [--force|-y]`: Removes specified profile and updates all managed configurations.

### `gitsetu credential <action>`
Standard Git credential helper broker protocol implementation:
- `gitsetu credential get`: Resolves credentials based on active directory profile context.
- `gitsetu credential store`: Persists credentials securely into OS keychain or `~/.config/gitsetu/.tokens`.
- `gitsetu credential erase`: Erases credentials for the current profile context.

---

## Diagnostics & Verification

### `gitsetu status`
Renders a structured, tabular layout of your entire GitSetu configuration state.
- Lists all registered profiles, bounded paths, and linked OpenSSH aliases.
- Dynamically highlights your **currently active profile** based on your active terminal directory context.

### `gitsetu doctor`
An advanced configuration health-scanner designed to identify silent environmental drift.
- Validates global `~/.gitconfig` syntax integrity and verifies the presence of managed identity blocks.
- Ensures the OpenSSH `Include` directive remains valid at the top of `~/.ssh/config`.
- Scans deep local `.git/config` files within mapped directory trees to surface overlapping or conflicting `user.email` hardcodes.

### `gitsetu verify`
Executes aggressive permissions and structural validation testing.
- Checks if generated private cryptographic keys (`~/.ssh/id_*`) possess strict POSIX `600` access boundaries (tolerates `644` under Windows NTFS emulation).
- Verifies SSH Agent socket connection state and pre-loaded signatures.

### `gitsetu prompt`
A specialized, ultra-fast context extractor designed strictly for sub-millisecond shell `$PS1` or Starship rendering integrations.
- Returns exactly one string (the active profile label) in `< 2ms` without spawning blocking subshells.
- Resolves nested paths via longest-prefix matching (most specific directory wins).
- Supports canonical Windows drive paths (`C:/...`) and case-insensitive directory matching on Windows and macOS.

---

## Vault Operations

### `gitsetu backup [out_file]`
The comprehensive export utility.
- Aggregates configuration schemas and cryptographic keys into a single `.tar` block.
- Enforces strict inline AES-256-CBC `-pbkdf2` encryption via native OpenSSL boundaries.

### `gitsetu restore <in_file>`
The bare-metal state re-construction tool.
- Decrypts target vaults and reconstructs structural mapping blocks transparently.
- Creates an automated pre-flight backup of existing state before restoring.

---

## System Operations

### `gitsetu run <profile> -- <cmd>`
Execute any command under a specific identity profile context without changing your current directory or altering configuration files.
- Injects environment variables (`GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, `GIT_COMMITTER_EMAIL`, and `GIT_SSH_COMMAND`).
- Enforces escaped double-quoting around SSH key paths containing spaces in `GIT_SSH_COMMAND` to prevent argument splitting.
- Example: `gitsetu run work -- git commit -m "fix"`

### `gitsetu update`
Executes the native OTA (Over-The-Air) update sequence.
- Pulls verified binary payloads exclusively via standard TLS/HTTPS domains.
- Atomically hot-swaps the local `~/.local/share/gitsetu` executable binary.

### `gitsetu guard --install` | `gitsetu guard --uninstall`
Toggles the fail-closed Pre-Commit Identity interceptor bounds inside the global `core.hooksPath` configuration matrix:
- `--install`: Installs and activates the global pre-commit hook in `~/.config/gitsetu/guard.sh` and configures `core.hooksPath`.
- `--uninstall`: Deactivates the global pre-commit hook and unsets `core.hooksPath`.

### `gitsetu teardown [--force] [--deep]`
**[Destructive Command]** The ultimate uninstall and nuclear escape hatch.
- Safely uninstalls GitSetu by completely purging all managed layout boundaries, sub-files, and configuration blocks from the host system cleanly.
- Restores the host Git environments to their pristine, pre-installation state without deleting your private SSH keys.
- `--deep`: Recursively strips matched local repository identity overrides.
- `--force`: Bypasses the confirmation prompt.

### `gitsetu --help, -h`
Displays the quick-reference help dialog in your terminal.

### `gitsetu --version, -v`
Prints the current version of the GitSetu CLI.


--- END OF FILE: reference/cli-commands.md ---

--- START OF FILE: reference/contributing.md ---

---
title: "Contributing Guide"
description: "Developer guidelines, coding conventions, test execution, and pull request workflows."
category: "reference"
slug: "reference/contributing"
---
# Contributing to GitSetu

**The uncompromising guidelines and structural constraints required for submitting codebase modifications.**

GitSetu is deliberately engineered to act as a deeply reliable, extremely portable Zero-Dependency bootstrapping compiler. Maintaining this architectural posture requires absolute adherence to strict language boundaries and POSIX execution principles.

If you are proposing codebase updates, new diagnostic scanners, or platform integrations, please carefully review the following strict guard rails before submitting pull requests.

---

## 1. Absolute Zero-Dependency Tolerance
GitSetu must successfully execute across legacy host systems completely offline.
- **No Interpreted Binaries:** Do not introduce integrations that require Go runtimes, Python interpreters, Node.js packages, or Rust compilers to resolve correctly.
- **Minimal Toolchains:** Rely strictly on `bash`, `git`, `ssh-keygen`, and core standard UNIX binaries (`grep`, `sed`, `awk`).

## 2. Bash 3.2 Compatibility Constraints
Because GitSetu must remain fully executable natively on legacy macOS endpoints, the entire codebase strictly targets **Bash 3.2**.
- **No Associative Arrays:** You may not utilize modern Bash 4.0+ features like `declare -A` associative structures.
- **POSIX Array Simulation:** Manage data matrices using standard indexed arrays and bounded iterators.
- **POSIX Subshell Offsets:** Minimize expensive `$(command)` `fork()` execution boundaries where possible. Utilize rapid internal variable pattern substitutions instead (`${var//search/replace}`).

## 3. Strict Concurrency Integrity
GitSetu executes in parallel headless CI/CD runners seamlessly. All persistent filesystem mutations **must** remain perfectly atomic.
- **Zero Inline File Overwrites:** Never utilize blind regex replacers (e.g., `sed -i`) natively against global target configurations. This creates catastrophic mid-write destruction windows during sudden SIGTERM events.
- **TMPDIR Swapping:** Always direct block modifications to heavily randomized temporary execution paths (`$TMPDIR/..._$$_${RANDOM}`), finalize validation, and subsequently apply them against primary targets utilizing single-cycle atomic `mv` replacements.

## 4. The Telemetry Boundary
We maintain a ruthless **Zero Telemetry** security posture.
Do not introduce integrations, analytics tracking, environment scanners, or crash-reporting dependencies that execute outbound background network requests. The repository codebase must remain perfectly verifiable and completely auditable.

---

## PR Submission Workflow

1. Fork the target `bhaskarjha-dev/gitsetu` repository.
2. Ensure your execution branch successfully passes local diagnostic boundaries (`gitsetu doctor` and verification testing paths).
3. **Testing Standards:** Run all automated regression tests before submitting PRs (`make test` or `bash tests/run_all.sh`). All 36 test suites must pass 100% green without regressions.
4. **Windows Testing Guidance:** Any changes affecting Windows paths, credentials, or shells should be verified directly in Git Bash and in an isolated environment using the Windows Sandbox Test Harness (`sandbox/launch_sandbox.ps1` or `sandbox/launch_sandbox.bat`).
5. **Code Style & Linting:** Run `make lint` to verify all shell scripts pass ShellCheck without warnings.
6. If introducing logic updates impacting standard core modules, explicitly test compilation output against cross-platform environments (e.g., native macOS Terminal vs Git Bash vs WSL).
7. Outline your proposed updates clearly within the PR description block, specifically detailing your testing environments, test results, and confirmation of Bash 3.2 adherence.


--- END OF FILE: reference/contributing.md ---

--- START OF FILE: reference/faq.md ---

---
title: "FAQ"
description: "Frequently asked questions regarding security, compatibility, key rotation, and performance."
category: "reference"
slug: "reference/faq"
---
# Frequently Asked Questions

**Common inquiries regarding GitSetu's operational philosophy, architecture constraints, and security limits.**

---

### General Operations

**Why utilize global `includeIf` boundaries instead of simply running `git config --local` inside each repository?**
Manually typing `git config --local` commands inside every newly cloned repository introduces massive operational friction and inevitable human error. Developers frequently forget to execute the command, resulting in personal credentials instantly leaking into corporate branch history upon their first commit. GitSetu orchestrates `includeIf` interceptors to ensure identities swap flawlessly *before* the commit phase activates.

**Do I need Go, Python, or Node.js to execute GitSetu?**
No. GitSetu is compiled strictly utilizing un-obfuscated, POSIX-compliant Bash 3.2. It executes natively across macOS, modern Linux targets, and headless WSL container environments relying exclusively on core host utilities (`bash`, `git`, `ssh-keygen`).

**Will GitSetu corrupt my pre-existing global Git aliases?**
Absolutely not. GitSetu respects a strict *Managed Block Protocol*. It only manipulates internal strings wrapped specifically inside its own `[gitsetu:managed:start]` boundary markers. Your custom `[alias]`, `[core]`, and syntax formatting blocks are completely ignored and preserved safely.

---

### Existing Manual Setups & Migration

**I already have manual `includeIf` configurations and custom `~/.ssh/config` host aliases. Will GitSetu overwrite or delete them?**
**No, absolutely not.** GitSetu is designed with a strict zero-destruction philosophy:
1. **In `~/.gitconfig`:** GitSetu writes exclusively between `# [gitsetu:managed:start]` and `# [gitsetu:managed:end]` sentinel markers. Any pre-existing manual `includeIf` directives, `[user]` identities, `[alias]` definitions, or custom configurations outside those markers remain completely untouched.
2. **In `~/.ssh/config`:** GitSetu never edits or reorders your existing `Host` blocks (such as `Host github-pro` or `Host personal`). It only prepends a single directive to the very top: `Include ~/.config/gitsetu/profiles/ssh_config`. All of your manual SSH aliases and key mappings underneath remain 100% functional and active.
3. **Pre-Modification Backups:** Before touching any configuration file, GitSetu automatically creates a timestamped backup in `~/.config/gitsetu/backups/` (`.gitconfig.<TIMESTAMP>.bak` and `config.<TIMESTAMP>.bak`).

**Do I have to start fresh from scratch if I already have manual profiles?**
**No.** GitSetu provides a smooth, automated transition via its built-in **Auto-Discovery Engine**:
- When you run `gitsetu setup --auto` (or during interactive `gitsetu setup`), the discovery engine parses your existing `~/.gitconfig` for existing `includeIf` directories, inspects `~/.ssh/` for existing keys (`id_ed25519_*`), and extracts emails from public keys.
- It pre-populates your profile blueprint with your existing paths and keys so you don't have to retype them.
- You can either choose **Peaceful Co-existence** (leave manual configs as-is and only use GitSetu for new profiles) or **Smooth Migration** (let GitSetu manage all profiles so you gain `gitsetu guard`, `gitsetu doctor`, and instant prompt status).

**What happens if both a manual `includeIf` and a GitSetu profile target the same folder?**
Git processes `~/.gitconfig` sequentially from top to bottom. If the same configuration key (such as `user.email`) is matched multiple times, Git's native precedence rule applies: **the last matching entry wins**. Because GitSetu's managed block is placed at the end of `~/.gitconfig`, GitSetu's profile will take precedence for that specific directory. For any other directories covered only by your manual configs, your manual setup continues to govern.

**What if I want to remove GitSetu and go back to my manual setup?**
Run `gitsetu teardown`. GitSetu will surgically excise only its managed block from `~/.gitconfig`, remove the `Include` line from `~/.ssh/config`, and remove `~/.config/gitsetu/`. Your manual `includeIf` blocks, SSH keys, and custom settings remain intact in their original state.

---

### Security Boundaries

**Where does GitSetu store HTTPS Personal Access Tokens?**
GitSetu fundamentally rejects storing plain-text credentials inside unencrypted filesystems. The internal Credential Broker engine proxies authentication tokens directly into your host operating system's native encrypted layers (e.g., Apple Keychain Access on macOS, or the Secret Service DBus API natively via `secret-tool` on Linux environments). 

**Does GitSetu track telemetry or phone home?**
No. GitSetu contains zero tracking dependencies, zero background daemon listeners, and zero crash reporting capabilities. It acts entirely offline. The only network call executed natively is explicitly user-triggered via the `gitsetu update` command, which communicates securely with verifiable GitHub release channels.

---

### Windows & WSL

**What are the prerequisites for running GitSetu on Windows?**
The only prerequisite on Windows is **Git for Windows** (which provides standard `git.exe` and `bash.exe`). You can install it via:
```powershell
winget install Git.Git
# Or download directly from: https://git-scm.com/download/win
```
Once Git for Windows is installed, GitSetu requires zero external runtimes (no Node.js, Python, or Go). GitSetu provides native Windows command shims (`gitsetu.cmd`, `gitsetu.ps1`, `gitsetu.exe`) so you can run all commands directly from **PowerShell**, **Command Prompt (CMD)**, **Windows Terminal**, and **VS Code**.

**Why does WinGet use `winget install BhaskarJha.GitSetu` instead of `winget install GitSetu`?**
Microsoft's official Windows Package Manager repository requires every package to have a unique, collision-proof Package Identifier formatted as `Publisher.PackageName`. `BhaskarJha.GitSetu` is the canonical identifier. Once WinGet updates its local search indexes, typing `winget install GitSetu` also automatically resolves to the official package.

**Does GitSetu operate properly on native Windows environments?**
Yes! GitSetu provides first-class support for Windows. When installed via `install.ps1`, WinGet, Scoop, or npm, GitSetu creates native command shims (`gitsetu.cmd`, `gitsetu.ps1`) so you can run `gitsetu` directly from **PowerShell**, **Command Prompt**, **Windows Terminal**, or **VS Code** — no need to open Git Bash.
1. **CLI Execution**: Run `gitsetu` commands from any Windows shell — PowerShell, CMD, Git Bash, or WSL.
2. **Native Windows Experience**: Because GitSetu compiles canonical Windows paths (`C:/path`) and case-insensitive `gitdir/i:` rules into `~/.gitconfig` and OpenSSH `~/.ssh/config`, the automatic identity switching and SSH key routing work natively everywhere across Windows—including **PowerShell**, **Command Prompt (CMD)**, **Windows Terminal**, **VS Code**, and GUI Git clients.
3. **Git Credential Manager (GCM)**: GitSetu automatically integrates with Microsoft's native Git Credential Manager on Windows.
4. **Isolated Testing**: Want to test without touching your machine? Run `.\sandbox\launch_sandbox.ps1` (or `launch_sandbox.bat`) to test GitSetu safely inside a disposable Windows Sandbox VM.

**How does credential brokering work inside headless WSL or minimal Linux containers?**
If native DBus secret tools (`secret-tool`) or GUI keychains are unavailable inside standard headless environments, GitSetu securely falls back to provisioning an isolated, restricted permissions vault file located at `~/.config/gitsetu/.tokens`. This file is strictly set to POSIX `600` permissions upon creation to guarantee containment.

---

### Zero-Trust Architecture & Edge Cases

**What happens if I have nested workspace folders (e.g. `~/work/` and `~/work/clients/acme/`)?**
GitSetu and Git resolve nested directory structures using **longest-prefix matching**. The most specific (longest) directory path takes precedence. When you navigate into `~/work/clients/acme/my-repo`, Git and GitSetu's guard and prompt engines match the `acme` profile rather than the parent `work` profile.

**Can I run `gitsetu setup` multiple times without losing my existing profiles?**
Yes. GitSetu is fully re-entrant and non-destructive. Running `gitsetu setup` automatically loads and re-hydrates existing profiles from `~/.config/gitsetu/profiles.conf`, allowing you to safely review, modify, or add profiles without overwriting your existing identities or SSH keys.

**Does GitSetu automatically create workspace directories if they don't exist yet?**
Yes. Whenever a profile is registered—whether through `gitsetu setup` or `gitsetu add`—GitSetu automatically provisions the target directory path using `mkdir -p`. In `--dry-run` mode, directory creation is simulated without filesystem mutation.

**How does GitSetu handle commits in unmapped or random directories?**
By default, GitSetu sets `[user] useConfigOnly = true` in the managed Git configuration, which causes Git to halt commits if no identity is matched, preventing accidental identity leaks. If you register a profile with an empty directory (`""`), GitSetu places that profile in a top-level `[include]` directive before conditional `[includeIf]` rules, establishing it as a safe global fallback identity for unmapped directories.


--- END OF FILE: reference/faq.md ---

--- START OF FILE: reference/manual-qa.md ---

---
title: "Manual QA Playbook"
description: "Step-by-step manual quality assurance test scenarios and cross-platform verification matrices."
category: "reference"
slug: "reference/manual-qa"
---
# GitSetu Manual QA Playbook

A step-by-step integration test checklist for verifying that every GitSetu feature works on a real machine. Run this before every release to ensure the README claims are true.

> **Prerequisites:** A machine with `bash`, `git`, and `ssh-keygen`. Two GitHub/GitLab accounts are ideal but not required — you can verify most features with one account.

---

## Pre-Flight

- [ ] Fresh terminal session (no leftover env vars from previous runs)
- [ ] Confirm bash version: `bash --version` (must be 3.2+)
- [ ] Confirm git version: `git --version`
- [ ] Confirm ssh-keygen exists: `which ssh-keygen`

---

## 1. Installation

> Verifies: README "Install" section

### macOS & Linux (POSIX Bash)
```bash
curl -sL https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/install.sh | bash
```

- [ ] Installer completes without errors
- [ ] `~/.local/share/gitsetu/` directory exists
- [ ] `gitsetu` command is available: `gitsetu --help`
- [ ] `git setu` alias works: `git setu --help`

### Windows (PowerShell)
```powershell
irm https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/install.ps1 | iex
```

- [ ] Installer completes without errors
- [ ] `%LOCALAPPDATA%\gitsetu\share` directory exists
- [ ] `gitsetu.cmd` and `gitsetu.ps1` exist in `%LOCALAPPDATA%\gitsetu\bin`
- [ ] `gitsetu --version` outputs `gitsetu v1.0.0` in PowerShell, CMD, and Windows Terminal
- [ ] `git setu --version` alias works identically

---

## 2. Interactive Setup

> Verifies: `gitsetu setup` wizard, SSH key generation, gitconfig injection

```bash
gitsetu setup
# Create profile "personal" with your personal email and ~/personal directory
# Create profile "work" with your work email and ~/work directory
```

- [ ] Wizard prompts for label, name, email, directory
- [ ] Wizard prompts for SSH key type (ED25519 default)
- [ ] SSH keypair generated: `ls ~/.ssh/id_ed25519_personal*` (private + .pub)
- [ ] SSH keypair generated: `ls ~/.ssh/id_ed25519_work*` (private + .pub)
- [ ] Key permissions are 600: `stat -c %a ~/.ssh/id_ed25519_personal` (or `stat -f %Lp` on macOS)
- [ ] `~/.gitconfig` contains `includeIf` block: `grep -A2 'includeIf' ~/.gitconfig`
- [ ] Profile gitconfig exists: `cat ~/.config/gitsetu/profiles/personal.gitconfig`
- [ ] SSH config has Include directive: `grep 'Include' ~/.ssh/config`
- [ ] Isolated SSH config has host alias: `grep -A3 'Host github-personal' ~/.config/gitsetu/profiles/ssh_config`
- [ ] Registry file exists: `cat ~/.config/gitsetu/profiles.conf`

---

## 3. Headless Add (Non-Interactive)

> Verifies: `gitsetu add` CLI mode

```bash
gitsetu add freelance "Your Name" freelance@example.com ~/freelance
```

- [ ] Command exits cleanly
- [ ] SSH key generated: `ls ~/.ssh/id_ed25519_freelance*`
- [ ] Profile appears in registry: `grep freelance ~/.config/gitsetu/profiles.conf`
- [ ] `~/.gitconfig` has new `includeIf` for `~/freelance/`

---

## 4. Status

> Verifies: `gitsetu status` display, active identity detection

```bash
cd ~/work && mkdir -p test-repo && cd test-repo && git init
gitsetu status
```

- [ ] All profiles listed with label, email, directory
- [ ] Active profile shows ✓ checkmark
- [ ] Correct profile is active for current directory

---

## 5. Directory-Scoped Identity (The "Magical Clone")

> Verifies: `includeIf` auto-switching (core README claim)

```bash
# In work directory
cd ~/work/test-repo
git config user.email   # Should show work email
git config user.name    # Should show work name

# In personal directory
cd ~/personal && mkdir -p test-repo && cd test-repo && git init
git config user.email   # Should show personal email
git config user.name    # Should show personal name
```

- [ ] Work directory returns work email
- [ ] Personal directory returns personal email
- [ ] No manual switching required

---

## 6. Identity Guard (Pre-Commit Hook)

> Verifies: `gitsetu guard` blocks wrong-identity commits

```bash
gitsetu guard --install
```

- [ ] Guard installs without errors
- [ ] `git config --global core.hooksPath` returns a valid path

```bash
# Force a mismatch
cd ~/work/test-repo
git config user.email "wrong@email.com"  # local override
echo "test" > testfile.txt && git add .
git commit -m "test"
```

- [ ] Commit is BLOCKED with "Identity mismatch detected!"
- [ ] Error shows expected vs actual email

```bash
# Fix and retry
git config --unset user.email
git commit -m "test"
```

- [ ] Commit succeeds with correct identity
- [ ] `git log --format="%ae" -1` shows work email

---

## 7. Shell Prompt Integration

> Verifies: `gitsetu prompt` output and speed

```bash
cd ~/work && gitsetu prompt    # Should output "[work]" or similar
cd ~/personal && gitsetu prompt # Should output "[personal]"
cd /tmp && gitsetu prompt       # Should output nothing (no profile)
```

- [ ] Output matches active profile for current directory
- [ ] Empty output when outside any profile directory
- [ ] Execution is fast (no visible lag)

**Speed test:**
```bash
time (for i in $(seq 100); do gitsetu prompt > /dev/null; done)
```

- [ ] 100 invocations complete in under 1 second

---

## 8. Credential Broker (HTTPS PATs)

> Verifies: `gitsetu credential` store/get/erase cycle

```bash
# During setup, provide a GitHub username and PAT when prompted
# Or manually test with dummy credentials:

printf 'protocol=https\nhost=github.com\nusername=testuser\npassword=ghp_test123\n\n' | gitsetu credential store

printf 'protocol=https\nhost=github.com\n\n' | gitsetu credential get
```

- [ ] `credential store` exits cleanly (no hang, no error)
- [ ] `credential get` returns `username=testuser` and `password=ghp_test123`
- [ ] Credentials stored in OS keychain (macOS: check Keychain Access; Linux: `secret-tool search service gitsetu`)
  - OR in file fallback: `cat ~/.config/gitsetu/.tokens`

```bash
printf 'protocol=https\nhost=github.com\nusername=testuser\npassword=ghp_test123\n\n' | gitsetu credential erase
printf 'protocol=https\nhost=github.com\n\n' | gitsetu credential get
```

- [ ] `credential erase` exits cleanly
- [ ] `credential get` returns empty (credentials removed)

---

## 9. Shell Autocompletion

> Verifies: TAB completion

```bash
source ~/.local/share/gitsetu/lib/completion.sh
gitsetu <TAB><TAB>
```

- [ ] Completion script sources without errors
- [ ] Subcommands are listed on TAB (setup, add, remove, status, etc.)
- [ ] Profile names complete on `gitsetu remove <TAB>`

---

## 10. Encrypted Backup & Restore

> Verifies: `gitsetu backup` / `gitsetu restore` lifecycle

```bash
gitsetu backup ~/test-vault.enc
# Enter encryption password when prompted
```

- [ ] Vault file created: `ls -la ~/test-vault.enc`
- [ ] File is encrypted (not readable): `file ~/test-vault.enc`

```bash
# Simulate restore on "new machine" by wiping config
mv ~/.config/gitsetu ~/.config/gitsetu-bak
gitsetu restore ~/test-vault.enc
# Enter same password
```

- [ ] Restore completes without errors
- [ ] Profiles restored: `gitsetu status`
- [ ] Registry matches original: `diff ~/.config/gitsetu/profiles.conf ~/.config/gitsetu-bak/profiles.conf`

```bash
# Cleanup
rm -rf ~/.config/gitsetu-bak ~/test-vault.enc
```

---

## 11. Profile Removal

> Verifies: `gitsetu remove` cleanup

```bash
gitsetu remove freelance
```

- [ ] Profile removed from registry: `grep freelance ~/.config/gitsetu/profiles.conf` (should return nothing)
- [ ] `includeIf` block removed from `~/.gitconfig`
- [ ] SSH host alias removed from `~/.config/gitsetu/profiles/ssh_config`
- [ ] SSH keys preserved on disk: `ls ~/.ssh/id_ed25519_freelance*` (still exists)

---

## 12. Idempotency

> Verifies: Safe to run multiple times (core claim)

```bash
gitsetu setup
# Re-add the same profiles with same settings
```

- [ ] No errors, no duplicates
- [ ] `~/.gitconfig` has exactly ONE `includeIf` per profile (not duplicated)
- [ ] `~/.config/gitsetu/profiles/ssh_config` has exactly ONE host block per profile
- [ ] SSH keys are NOT overwritten (prompted to skip/keep)

---

## 13. Doctor

> Verifies: `gitsetu doctor` diagnostic tool

```bash
gitsetu doctor
```

- [ ] All checks pass on a healthy setup
- [ ] Output goes to stderr (not stdout): `gitsetu doctor > /dev/null` (should still see output)

---

## 14. Verify

> Verifies: `gitsetu verify` infrastructure check

```bash
gitsetu verify
```

- [ ] SSH key existence and permissions verified
- [ ] Git config verified
- [ ] All checks report OK

---

## 15. Teardown & Uninstall

> Verifies: Clean removal (README "Uninstallation" section)

```bash
gitsetu teardown
```

- [ ] Managed blocks removed from `~/.gitconfig`
- [ ] Include directive removed from `~/.ssh/config`
- [ ] Custom user content in both files preserved
- [ ] SSH keys intentionally preserved

```bash
gitsetu teardown --deep
```

- [ ] Local repo identity overrides also cleaned

```bash
curl -sL https://raw.githubusercontent.com/bhaskarjha-dev/gitsetu/main/uninstall.sh | bash
```

- [ ] `~/.local/share/gitsetu/` removed
- [ ] `gitsetu` symlink removed
- [ ] `git setu` no longer works

---

## 16. Cross-Platform Spot Checks

> Run on each supported platform if available

### macOS
- [ ] `detect_os` returns `macos`
- [ ] Credential broker uses `security` (Keychain)
- [ ] SSH key generation works with macOS `ssh-keygen`

### Linux
- [ ] `detect_os` returns `linux`
- [ ] Credential broker uses `secret-tool` or file fallback
- [ ] SSH key generation works

### Windows (Git Bash)
- [ ] `detect_os` returns `gitbash`
- [ ] CRLF self-healing activates (check for `\r` in config files)
- [ ] `safe.directory` rules injected for shared mounts

### WSL
- [ ] `detect_os` returns `wsl`
- [ ] Correctly distinguishes from native Linux

---

## Release Checklist

After all manual tests pass:

- [ ] `make test` (or `bash tests/run_all.sh`) — all 36 regression test suites pass 100% green
- [ ] Windows Sandbox verification — `.\sandbox\launch_sandbox.ps1` (or `launch_sandbox.bat`) boots disposable VM, runs all 36 test suites, live multi-profile scenarios, and 31-phase empirical audit (107 checks)
- [ ] `make lint` — ShellCheck clean
- [ ] CHANGELOG.md updated
- [ ] Version bumped in `gitsetu` (if applicable)
- [ ] README claims match actual behavior
- [ ] Tag and release


--- END OF FILE: reference/manual-qa.md ---

--- START OF FILE: reference/troubleshooting.md ---

---
title: "Troubleshooting"
description: "Diagnostic workflows and solutions for SSH permission errors, keychain locks, and hook conflicts."
category: "reference"
slug: "reference/troubleshooting"
---
# Troubleshooting & Diagnostics

**A comprehensive guide to rapidly surfacing and resolving environmental configuration drift.**

GitSetu is engineered to self-heal and fail-closed natively, but localized Git configurations, OS keychain constraints, and complex virtualization bounds frequently introduce obscure connectivity issues. This reference provides immediate resolution paths for the most common errors.

---

## ⚡ First-Line Defense: Built-in Scanners

Before executing manual log investigation, rely on GitSetu's built-in advanced diagnostic execution paths:

### `gitsetu status`
Instantly surfaces context. Run this inside the broken target repository. It evaluates your current directory path against global `includeIf` matrices and explicitly states which identity Git currently *believes* it should execute under.

### `gitsetu doctor`
The ultimate configuration health scanner. It deeply verifies global `~/.gitconfig` syntax integrity, `~/.ssh/config` block placement, agent availability, and cross-checks local repository state overrides.

---

## 🔑 OpenSSH Authentication Collisions

> [!WARNING]
> If a `git push` or `git fetch` operation hangs or immediately returns **`Permission denied (publickey)`**, your public SSH signature is either missing from your Git hosting provider, or OpenSSH is aggressively returning cached failures.

### Resolution: Unmapped Public Keys
If GitSetu generated a fresh keypair for your target profile, you **must** manually associate the public side of that signature with your upstream provider (GitHub, GitLab, Bitbucket).
1. Output the public signature: `cat ~/.ssh/id_ed25519_<profile>.pub`
2. Navigate to your provider's SSH Settings portal and paste the block exactly.
3. Verify connection manually using the isolated alias: `ssh -T git@github-<profile>`

> [!IMPORTANT]
> **"Key already exists" Error on GitHub:** GitHub strictly enforces a 1-to-1 mapping. Each SSH public key can only be attached to **ONE** GitHub account. If you see this error, you are trying to add a key to your `work` account that is already attached to your `personal` account. You must generate a unique key for each account (which `gitsetu setup` handles automatically).

> [!NOTE]
> **"Could not resolve hostname github-pro":** GitSetu generates host aliases (like `github-pro`) **purely for testing connectivity**. You do NOT need to use them when cloning repositories. You can continue cloning using standard `git@github.com:...` strings.

### Resolution: Agent Saturation ("Too many authentication failures")
If you manually loaded multiple legacy keys into your global `ssh-agent`, target hosts may disconnect after your host attempts to cycle blindly through incorrect signatures.
GitSetu explicitly sets `IdentitiesOnly = yes` in your generated profiles to mitigate this, but if problems persist, restart the SSH agent or use `ssh-add -D` to clear transient caches.

---

## 🛑 Pre-Commit Identity Guard Blocks

```text
[GitSetu Guard] BLOCKING COMMIT! Identity mismatch detected.
Expected Email: dev@company.com (Target Profile: 'work')
Active Runtime Email: personal@example.com
```

The GitSetu Pre-Commit Identity Guard threw a fatal error to intentionally protect your commit history from leaking. 

### Resolution: Local Configuration Overrides
The most common cause of this error is that a developer manually executed `git config user.email` inside the target directory at some point in the past. This places an explicit override block inside the hidden `.git/config` file, overriding GitSetu's conditional routing matrices.

To clear the conflict and allow GitSetu to resume control:
```bash
git config --local --unset user.email
git config --local --unset user.name
```

> [!TIP]
> **Bypassing the Guard:** If you intentionally want to bypass the Identity Guard for a specific, isolated commit without clearing your local overrides, you can utilize Git's native `--no-verify` flag: `git commit -m "wip" --no-verify`.

---

## ⚙️ Path Interception Failures (`includeIf` ignoring directories)

If you navigate into a configured directory and your terminal `$PS1` integration or `gitsetu status` command still reports your global fallback identity, Git is refusing to execute the conditional intercept rule.

### Resolution: Symlinks & Virtualization Bounds
Git is highly pedantic regarding target path strings.
1. **Trailing Slashes:** Ensure the mapped path ends in `/`. GitSetu handles this natively during `setup`.
2. **Mount Point Normalization:** If you are operating inside WSL or virtualized Windows mounts (`/mnt/c/`), ensure you utilized the absolute Linux `/mnt/c/` path structure during `gitsetu setup`, not the abstract Windows path.
3. **Safe Directory Checks:** If your target `.git` repository folder is owned by a different internal OS user (e.g. `root` inside Docker mounts), Git aborts `includeIf` logic instantly. Utilize Git's native safe directory bypass: `git config --global --add safe.directory /path/to/target/repository`.

---

## 🪟 Windows-Specific Considerations

### NTFS Key Permissions (`644` vs `600`)
Under Linux/macOS, OpenSSH strictly demands `chmod 600` for private keys. On Windows NTFS filesystems, POSIX file permissions do not natively exist and Git Bash emulates permissions as `644`. 
- **GitSetu Behavior**: `gitsetu verify` automatically tolerates `644` on Windows (`gitbash`), preventing false-positive errors.
- **OpenSSH on Windows**: Native Windows OpenSSH (`C:\Windows\System32\OpenSSH\ssh.exe`) relies on Windows NTFS Access Control Lists (ACLs) instead of POSIX bits.

### Path Casing & Virtual Mount Points
- **Drive Letters**: Always use forward slashes in Git configurations (e.g. `C:/Users/name/work` rather than `C:\Users\name\work`). GitSetu automatically normalizes all paths to canonical `C:/path` format.
- **Case Sensitivity**: Windows paths are case-insensitive. GitSetu automatically injects `gitdir/i:` so directory matching works whether paths are referenced with uppercase or lowercase drive letters (`C:` vs `c:`).

### Isolated Verification via Windows Sandbox
If you want to verify GitSetu, test adding profiles, or debug configurations in total isolation from your host:
```powershell
# Native PowerShell:
powershell -ExecutionPolicy Bypass -File .\sandbox\launch_sandbox.ps1

# Or via Command Prompt / Explorer:
.\sandbox\launch_sandbox.bat
```
This boots a clean, disposable Windows Sandbox container, runs the entire regression test suite (all 36 test suites), and simulates multi-profile Git commits without any risk to your host setup.

---

## ☢️ The Nuclear Option: Clean State Teardown

If your environment is irrecoverably corrupted by cross-platform manual file tampering, execute GitSetu's native cleanup utility.

```bash
gitsetu teardown
```

This operation meticulously cleans all GitSetu managed layout boundaries from `~/.gitconfig` and OpenSSH paths safely without modifying your localized aliases, allowing you to execute `gitsetu setup` seamlessly against a fresh baseline.


--- END OF FILE: reference/troubleshooting.md ---