From 234817969d357a553b8f6ce0197824f7068c5664 Mon Sep 17 00:00:00 2001
From: Levi Neely <141506390+lneely@users.noreply.github.com>
Date: Wed, 22 Jul 2026 19:00:57 +0200
Subject: [PATCH] docs: add workspaces documentation to README

---
 README.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 88 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 2db5800..000a92f 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,16 @@ and worktree support — all integrated with Kate's project module.
 - **Open project** — double-click to open worktree in Kate
 - **Copy path** — right-click to clipboard
 
+### Workspaces Tab
+
+- **List** of sibling workspaces with branch info; current workspace shown in bold
+- **Create** — dialog prompts for source workspace and branch name, with branch auto-completion from all repos in source
+- **Remove** — removes all worktrees and deletes workspace directory (with confirmation); runs `OnRemove` hook if configured
+- **Prune** — runs `git worktree prune` across all repos in the source workspace
+- **Open** — double-click to switch Kate to another workspace
+- **Copy path** — right-click to clipboard
+- **Repo selector** — combo dropdown appears in workspace mode to switch active repository within the workspace
+
 ### Indicators
 
 - **Panel header** — shows repo name, branch, dirty state with color coding
@@ -85,24 +95,90 @@ This convention means:
 - The name tells you both the repo and the branch
 - No collisions if you have worktrees from multiple repos in the same parent directory
 
-### Recommended Workflow
-
-1. **Start a feature** — go to the Branches tab, select the base branch,
-   right-click → "Create worktree" (or use the Worktrees tab → Create button)
-2. **Work in isolation** — double-click the worktree entry to open it as a
-   Kate project. Each worktree has its own working directory, so you can
-   switch between features without stashing.
-3. **Review another branch** — create a worktree for a colleague's branch
-   to review their code without disrupting your current work.
-4. **Clean up** — when done with a feature branch, remove the worktree from
-   the Worktrees tab. The branch remains intact for merging.
-
 ### Kate Project Detection
 
 Git++ automatically creates a `.kateproject` file in each new worktree so
 that Kate's project plugin recognizes it immediately. The project uses git
 for file listing, so the file tree shows exactly what git tracks.
 
+## Workspace Workflow
+
+Workspaces extend the worktree concept to **multi-repo projects**. A workspace
+is a directory containing multiple git repositories that you work on together
+— for example a microservices monorepo split into multiple git repos, or a
+project using git submodules.
+
+### What Is a Workspace?
+
+A workspace is detected automatically when:
+
+1. A directory contains a `.kateworkspace` file, **or**
+2. A directory contains two or more subdirectories that each have a `.git`
+   folder (heuristic detection), **or**
+3. The project root contains a `.gitmodules` file (submodule monorepo)
+
+The `.kateworkspace` file is an INI file with a `[workspace]` section:
+
+```ini
+[workspace]
+source=../main-workspace
+```
+
+The `source` key points (relative or absolute) to the "source" workspace —
+the original from which this workspace was derived. A value of `.` means
+this workspace is itself the source.
+
+### How It Works
+
+When you create a workspace, Git++ performs these steps:
+
+1. Prompts for a **source workspace** (the multi-repo directory to branch from)
+   and a **branch name** (with auto-completion from all branches across all
+   repos in the source)
+2. Creates a new sibling directory next to the source
+3. Runs `git worktree add` in each repo inside the source, checking out (or
+   creating) the named branch in the new workspace
+4. Writes a `.kateworkspace` file pointing back to the source
+5. Generates `.kateproject` files in each repo subdirectory
+
+The resulting layout looks like:
+
+```
+~/projects/
+├── my-platform/              ← source workspace
+│   ├── .kateworkspace        ← source = "."
+│   ├── frontend/             ← git repo (main branch)
+│   ├── backend/              ← git repo (main branch)
+│   └── shared-lib/           ← git repo (main branch)
+│
+└── my-platform.ISSUE-42/     ← derived workspace
+    ├── .kateworkspace         ← source = "../my-platform"
+    ├── frontend/             ← worktree (ISSUE-42 branch)
+    ├── backend/              ← worktree (ISSUE-42 branch)
+    └── shared-lib/           ← worktree (ISSUE-42 branch)
+```
+
+### OnRemove Hook
+
+The `.kateworkspace` file can include a `[hooks]` section:
+
+```ini
+[hooks]
+OnRemove=/path/to/script.sh %d
+```
+
+When a workspace is removed, Git++ executes this command before deleting
+files. The `%d` placeholder is replaced with the workspace directory path.
+This is useful for cleanup tasks like deregistering services, closing
+related PRs, or notifying teammates.
+
+### Repo Selector
+
+When Git++ detects workspace mode, a combo box appears at the top of the
+panel listing all repositories in the workspace. Selecting a different repo
+switches the entire Git++ view (status, branches, stashes, worktrees, log)
+to that repository, and opens its `.kateproject` in Kate's project view.
+
 ## Building
 
 Supports both KF5 (Kate on Qt5) and KF6 (Kate on Qt6). The build system