docs: add workspaces documentation to README
This commit is contained in:
Levi Neely
parent
60d86ab690
commit
234817969d
100
README.md
100
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
|
||||
|
|
|
|||
Loading…
Reference in New Issue