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

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:

[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:

[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

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

Or use the provided Makefile:

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. See the LICENSE file for details.