146 lines
5.3 KiB
Markdown
146 lines
5.3 KiB
Markdown
# 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.
|