kate-gitplusplus/README.md

# Git++ Kate Plugin

A Git integration plugin for Kate designed for complex projects. Worktrees,
workspaces, multi-repo setups, and submodule monorepos are first-class
features — not afterthoughts. Tabs you don't need can be hidden, so the
interface stays simple until you need more. A tabbed side panel provides
status tracking, branch management, stash operations, worktree and workspace
support, all integrated with Kate's project module.

## Features

### Status Tab

- **Live file status** — tree view showing Staged, Changed, and Untracked files
- **Stage / Unstage** — select files and click, or double-click to toggle
- **Discard changes** — revert selected files (with confirmation)
- **Commit** — inline message editor with amend support
- **Amend** — checkbox loads last commit message for editing
- **Push / Pull / Fetch** — with real-time progress spinner and git transfer output
- **Stash** — quick-save button in the toolbar
- **Open commit** — view any commit's diff in the editor
- **Auto-refresh** — watches `refs/heads` for branch changes; status refreshes automatically after git operations

### Branches Tab

- **Filterable list** of all local and remote branches
- **Checkout** — double-click or button; remote branches auto-create local tracking branch
- **Create branch** — dialog shows source branch name
- **Delete branch** — with confirmation
- **Compare** — diff between selected branch and current, opens in editor with syntax highlighting
- **Create worktree** — from any branch (see Worktrees below)
- **Copy branch name** — right-click to clipboard

### Stashes Tab

- **List** of all stashes with their messages
- **Save** — with optional message
- **Apply** — applies selected stash (keeps it)
- **Pop** — applies and removes selected stash
- **Drop** — removes selected stash (with confirmation)
- **Diff** — view stash contents in the editor

### Worktrees Tab

- **List** of all active worktrees with path, commit, and branch
- **Create** — editable combo box lets you pick an existing branch or type a new one
- **Remove** — deletes the worktree directory (with confirmation)
- **Prune** — clean up stale worktree references
- **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
  - Green `○` when clean
  - Orange `●` with file counts when dirty
  - Red `⚠ DETACHED` with dark background when HEAD is detached
- **Status bar** — persistent branch + dirty indicator visible even when panel is hidden
- **Remote operations** — animated spinner with progress streaming during push/pull/fetch

## Worktree Workflow

Git worktrees let you have multiple branches checked out simultaneously in
separate directories, without needing multiple clones. Git++ makes this
practical for daily use.

### How It Works

When you create a worktree from a branch, Git++ creates a sibling directory
next to your main repo using the naming convention:

```
{repo-name}.{branch-name}
```

For example, if your repo is at:
```
~/projects/myproject/
```

And you create a worktree for branch `ISSUE-123_my-feature`, it creates:
```
~/projects/myproject.ISSUE-123_my-feature/
```

This convention means:
- Worktrees are always next to the main repo (easy to find)
- The name tells you both the repo and the branch
- No collisions if you have worktrees from multiple repos in the same parent directory

### 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
auto-detects which framework is available, preferring KF6.

**Dependencies** (install the set matching your Kate version):

- KF6: `libkf6texteditor-dev`, `libkf6i18n-dev`, `libkf6coreaddons-dev`, `qt6-base-dev`, `extra-cmake-modules`
- KF5: `libkf5texteditor-dev`, `libkf5i18n-dev`, `libkf5coreaddons-dev`, `qtbase5-dev`, `extra-cmake-modules`

```sh
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/usr -Wno-dev
make -j$(nproc)
sudo make install
```

Or use the provided Makefile:

```sh
make install
```

## Installation Path

The plugin installs to Kate's KTextEditor plugin directory:

- KF6: `/usr/lib64/qt6/plugins/kf6/ktexteditor/gitplusplus.so`
- KF5: `/usr/lib/x86_64-linux-gnu/qt5/plugins/ktexteditor/gitplusplus.so`

The exact path depends on your distribution's library layout.

Enable it in Kate → Settings → Configure Kate → Plugins → "Git++".

## Project Integration

Git++ reads the project base directory from Kate's project plugin
(`kateprojectplugin`). When you switch projects or open a new one, all tabs
refresh automatically. If no project is open, it falls back to the directory
of the active file.

## License

This project is licensed under the [GNU General Public License v3.0 or later](https://www.gnu.org/licenses/gpl-3.0.html). See the [LICENSE](LICENSE) file for details.