From 9898e1d486b6b3c52269f38d47979bba4f15e3e3 Mon Sep 17 00:00:00 2001
From: inx <inx@inx.wf>
Date: Tue, 27 Jan 2026 15:25:07 +0800
Subject: [PATCH] chore(docs): add comprehensive README and usage guide Adds a
 detailed README.md covering: - Project core value proposition (Security &
 Isolation). - Installation instructions. - Detailed usage workflows (Setup,
 Exec, Switch, Management). - Explanation of the "Blind Injection" security
 design. - Configuration directory structure (XDG).

---
 README | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 README

diff --git a/README b/README
new file mode 100644
index 0000000..bca8d8f
--- /dev/null
+++ b/README
@@ -0,0 +1,116 @@
+# Gosh (Git Operations SHell)
+
+**Gosh** is a lightweight, secure, and idempotent wrapper for Git, written in Rust. It solves the chaos of managing multiple Git identities (Work vs. Personal) by strictly isolating configurations and preventing accidental identity leaks.
+
+## 🚀 Features
+
+* **🛡️ Fail-Safe Security**: Uses "Blind Injection" to forcibly wipe global identity keys before applying a profile. If your profile lacks a key, Gosh fails securely rather than falling back to your global `~/.gitconfig`.
+* **⚡ Ephemeral Execution**: Run commands like `gosh work commit` without modifying any files on disk. Perfect for one-off fixes.
+* **💾 Persistent Switching**: Permanently bind a repository to an identity using Git's native `[include]` directive.
+* **🛠️ Zero Config Setup**: Automatically handles `clone` and `init` setup, applying the correct identity immediately.
+* **📂 Portable Profiles**: Profiles are stored in `~/.config/gosh/profiles/`, designed to be synced via a private Git repository.
+
+## 📦 Installation
+
+### From Source
+
+```bash
+cargo install --path .
+
+```
+
+## 📖 Usage
+
+### 1. Management: Create Identities
+
+Gosh manages identities as "Profiles".
+
+```bash
+# Syntax: gosh -c <Name> <Email> <ProfileID>
+gosh -c "Alice Work" "alice@company.com" "work"
+gosh -c "Alice Hobby" "alice@gmail.com" "personal"
+
+# List all profiles
+gosh -l
+
+# Edit a profile (e.g., to add signingkey or sshCommand)
+gosh -e work
+
+```
+
+### 2. Workflow A: Setup New Projects (Recommended)
+
+When you clone or init a repository, Gosh automatically sets up the local config.
+
+```bash
+# Clones the repo and immediately binds it to the "work" profile
+gosh work clone git@github.com:company/backend.git
+
+# Inside the repo, you can now just use standard git
+cd backend
+git config user.email # Output: alice@company.com
+
+```
+
+### 3. Workflow B: One-off Commands (Exec Mode)
+
+Run a command with a specific identity *without* modifying the repository config.
+
+```bash
+# Temporarily commit as "personal" in a work repo (e.g., fixing a typo)
+gosh personal commit -m "Fix typo"
+
+# Verification
+gosh personal config user.email
+
+```
+
+### 4. Workflow C: Switch Identity (Persistent)
+
+Change the identity bound to an existing repository.
+
+```bash
+cd my-repo
+gosh work
+
+# If the repo has "dirty" config (manually set user.name), force overwrite it:
+gosh work -f
+
+```
+
+## ⚙️ Configuration
+
+Gosh follows the XDG Base Directory specification.
+
+* **Config File**: `~/.config/gosh/gosh.toml`
+* **Profiles**: `~/.config/gosh/profiles/*.gitconfig`
+
+On the first run, Gosh will automatically create these directories and a default configuration file.
+
+### Environment Variables
+
+* `GOSH_CONFIG_PATH`: Override the config directory (Useful for NixOS or testing).
+* `GOSH_MOCKING=1`: Dry-run mode. Prints the constructed `git` command to stderr instead of executing it.
+
+## 🔒 Security Design: Blind Injection
+
+In **Exec Mode**, Gosh does **not** read your local configuration to decide what to override. Instead, it aggressively injects empty values for sensitive keys before applying your profile.
+
+**Example command generated by Gosh:**
+
+```bash
+git \
+  -c user.name="" \       # 1. Wipe potential leaks
+  -c user.email="" \
+  -c user.signingkey="" \
+  -c commit.gpgsign=false \
+  -c include.path=~/.config/gosh/profiles/work.gitconfig \ # 2. Apply Profile
+  commit ...
+
+```
+
+This ensures that if your "work" profile is missing a GPG key, Git will error out ("Secret key not available") rather than silently using your personal GPG key from `~/.gitconfig`.
+
+## 📄 License
+
+[BSD 2-Clause License](./LICENSE)
\ No newline at end of file