# Git++ Kate Plugin

A comprehensive Git integration plugin for the Kate text editor. Provides a
tabbed side panel with status tracking, branch management, stash operations,
and worktree 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 `.git/index` and `HEAD` for external changes

### 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

### 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

### 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.

## 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.