Release v0.4.1: Documentation Refinement

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-01-09
+### Changed
+- Improved README with a comparison table and architectural explanation.
+- Reorganized installation instructions for better user experience.
+
 ## [0.4.0] - 2026-01-08
 ### Added
 - **Active Config Visualizer**: Highlights the session-active configuration with an asterisk (`*`) in the list display.

README.md

@@ -10,11 +10,18 @@
 
 Managing multiple Google Cloud projects usually involves `gcloud config configurations activate ...`, which changes the global state. This becomes dangerous when you have multiple terminals open—running a command in one terminal might target the wrong project because you switched configs in another tab.
 
-`gsw` solves this by offering:
-1.  **Safety by Default**: `gsw <config>` limits configuration changes to only the *current shell session* (using `CLOUDSDK_ACTIVE_CONFIG_NAME`).
-2.  **Global Control**: Use `gsw -g <config>` when you actually want to change the default for all terminals.
-3.  **Speed**: Shorter command with tab completion saves you keystrokes.
-4.  **Simplicity**: No complex setup or dependencies. Just shell functions.
+### Comparison
+
+| Feature | `gsw` | `gcloud activate` | `direnv` |
+| :--- | :--- | :--- | :--- |
+| **Scope** | Session (Current tab) | Global (All tabs) | Directory-based |
+| **Switching** | Ad-hoc (Anywhere) | Ad-hoc (Anywhere) | Automatic (On `cd`) |
+| **Safety** | High (Isolated) | Low (Side effects) | High (Context-aware) |
+| **Setup** | Zero | Zero | Needs `.envrc` files |
+
+### How it works
+
+`gsw` is a clean wrapper around the `CLOUDSDK_ACTIVE_CONFIG_NAME` environment variable. When you run `gsw <config>`, it exports this variable to your current shell session. Since the Google Cloud SDK honors this variable over the global configuration, you get instant, safe isolation without any complex magic.
 
 ## Features
 
@@ -30,12 +37,22 @@ Managing multiple Google Cloud projects usually involves `gcloud config configur
 
 ## Installation
 
-### Method 1: One-Line Install (Recommended)
+`gsw` is just a shell script. Choose the method that fits your workflow.
 
-Run this command to install `gsw` to `~/.gsw` and update your `.zshrc` automatically:
+### Method 1: Zsh Plugin Managers
 
-```bash
-curl -sL https://raw.githubusercontent.com/sakebook/gsw/main/install.sh | bash
+If you use a plugin manager, this is the cleanest way to keep `gsw` updated.
+
+**zplug:**
+```zsh
+zplug "sakebook/gsw", use:gsw.sh
+```
+
+**sheldon:**
+```toml
+[plugins.gsw]
+github = "sakebook/gsw"
+use = ["gsw.sh"]
 ```
 
 ### Method 2: Manual Install
@@ -49,25 +66,14 @@ curl -sL https://raw.githubusercontent.com/sakebook/gsw/main/install.sh | bash
     source ~/.gsw/gsw.sh
     ```
 
-### Plugin Managers (Zsh)
-
-<details>
-<summary>Click to expand configuration examples</summary>
+### Method 3: One-Line Install (Fastest)
 
-**zplug:**
-```zsh
-zplug "sakebook/gsw", use:gsw.sh
-```
+Run this command to install `gsw` to `~/.gsw` and update your `.zshrc` automatically:
 
-**sheldon:**
-```toml
-[plugins.gsw]
-github = "sakebook/gsw"
-use = ["gsw.sh"]
+```bash
+curl -sL https://raw.githubusercontent.com/sakebook/gsw/main/install.sh | bash
 ```
 
-</details>
-
 ## Usage
 
 ### Session Switch (Default)

gsw.sh

@@ -2,7 +2,7 @@
 
 # gsw: Google Switch
 # Easily switch between gcloud configurations
-GSW_VERSION="v0.4.0"
+GSW_VERSION="v0.4.1"
 
 function gsw() {
   # Check if gcloud is installed