---
url: https://clusto.app/docs/git-panel.md
description: >-
  Inspect repository status and diffs, then commit, pull, or push from the
  Clusto sidebar.
---

# Git Changes Panel

The Git tab is on by default in Terminals and in Chats (when the chat works in a
project root). In SSH it is off by default; turn it on from the sidebar's sliders button (see
[Panels per view](/file-explorer#panels-per-view)). It needs a project.

The right sidebar's **Git** tab shows the working-tree status of the active
project's git repository, with a built-in unified-diff viewer (opened as a tab on
your terminal's pane) for any selected file plus quick actions for **commit**,
**pull**, and **push**.

## What it shows

* **Branch chip** at the top with ahead/behind counters when an upstream is
  configured.
* **Staged** section - files with index-vs-HEAD changes (`git add`-ed but
  not committed).
* **Changed** section - files with worktree-vs-index changes.
* **Untracked** section - files not in git, marked with `??`.
* **Selection checkboxes** on each row so you can choose files for bulk
  stage / unstage operations. A selection bar appears when rows are checked.
* A **diff viewer** that displays the unified patch for whichever file is
  selected, with `+`/`-` lines colorized. In Terminals it opens as a tab on the
  focused terminal's pane; see [Diffs open as a tab](#diffs-open-as-a-tab).
* **Commit / Pull / Push** buttons for quick actions in the sidebar. They only
  show when the project is a git repository; without a project the panel
  explains why there is nothing to show.
  `Commit` opens a dialog and commits the currently staged changes only.
  `Pull` runs `git pull --ff-only` so the UI never blocks on an interactive merge flow.
  `Push` runs `git push` for the current branch/upstream.
* **Stage / Unstage** buttons in the selection bar for moving the checked files
  in or out of the index without leaving the app.

Clicking any row opens its diff. Untracked files show their full contents as
an added-file diff, so a new file is never a blank "No diff".

## Diffs open as a tab

In Terminals and Chats, clicking a changed file opens its diff as a **diff tab**
on the pane of the focused terminal or chat, instead of in a small panel at the bottom of the
Git tab. The pane gets a tab strip: the terminal first (labelled with the
session name), then its file and diff tabs. The strip appears only while there
are tabs, and the terminal keeps running under a diff tab. Click the terminal
tab to see it again unchanged.

* There is one diff tab per terminal or chat. Opening another diff re-aims that tab at
  the new file rather than opening a second one.
* The diff header has **Open in editor**, which opens the file as another tab
  in the [editor](/editor), and **Close**, which removes the diff tab. You can
  also close it with the X on the tab or a middle-click. Closing the last tab
  hides the strip.
* Tabs belong to the terminal session, not to the pane. They follow the session
  into another layout, come back after an app restart, and are removed when the
  session is killed.
* On phones the tabs work the same way and the strip scrolls sideways.
* Chats work the same way: the diff opens as a tab on the chat's pane, and
  auto-open re-aims that tab at the changed file in the background. SSH
  sessions have no project, so they have no Git diffs.

## Live updates

The panel updates on its own. It shares the daemon's project file watcher with
the Files tab, so an edit, a build or an agent write refreshes the change list
and any open diff without clicking Refresh or switching windows. An open diff
stays on screen across a status refresh, and the watch subscriptions are
restored after a reconnect.

The watcher skips `.git`, so a commit or checkout made in a terminal shows up
when the workspace gains focus. The refresh button in the panel header forces a
re-fetch at any time. Background polling stays **off** to save battery on
Android.

## Open diffs of changed files

When a file in the focused session's project changes on disk, the right sidebar
opens the **Git** tab and sends that file's diff to the diff tab in the
background, so the terminal stays on screen and typing is not interrupted. If
the diff tab is the one showing, it follows each change. A collapsed sidebar
expands to show the Git tab. Use it to watch what an agent is editing as it
happens.

* It works with any agent CLI (Claude Code, Codex, OpenCode and others) and for
  projects on other nodes, because it follows the filesystem watcher rather than
  agent hooks.
* It cannot tell who wrote the file, so your own editor saves show up too.
* It needs the Git tab enabled on that surface. It is on by default in Terminals
  and Chats; turn it on in SSH from the sidebar's sliders button.
* Desktop only. Phones never auto-open the sidebar.

The behavior is on by default. Switch it off with **Open diffs of changed
files** in **Settings > Appearance > Right sidebar**, or press **F1** and run
**Stop opening diffs of changed files**. The palette command **Open diffs of
changed files automatically** turns it back on.

The panel needs the native desktop or mobile app; in the web app it shows a
notice instead and git is managed from a terminal session.

If the project's working directory is not a git repository, the panel says
so without raising an error. Genuine errors (`git` not on PATH, peer
unreachable for a project on another node) are surfaced as a banner.

## Wire protocol

### `GitStatus`

```jsonc
// client → daemon
{ "type": "git_status", "project_id": "<uuid>" }
```

The daemon runs, in the project's working directory:

```
git status --porcelain=v2 --branch -z
```

with `LANG=C` and `LC_ALL=C` for parse stability, and parses the result
into a `git_status_result`.

```jsonc
// daemon → client (success)
{
  "type": "git_status_result",
  "project_id": "<uuid>",
  "is_repo": true,
  "branch": "main",
  "upstream": "origin/main",
  "ahead": 1,
  "behind": 0,
  "staged":   [{ "path": "src/lib.rs", "status": "M" }],
  "unstaged": [{ "path": "README.md", "status": "M" }],
  "untracked": ["new.txt"]
}
```

`is_repo = false` is **not** an error - it means the directory is not a
git repository (or `git` exits with the "not a git repository" message).
`git_error` is reserved for project-not-found, peer-unreachable, and
spawn-failure cases.

`status` is the single-letter porcelain v2 code: `M` modified, `A` added,
`D` deleted, `R` renamed, `C` copied, `T` type changed, `U` unmerged. For
renames and copies the `old_path` field carries the original path.

### `GitDiff`

```jsonc
// client → daemon
{ "type": "git_diff", "project_id": "<uuid>", "path": "src/lib.rs", "staged": false }
```

`staged = false` returns the worktree-vs-index diff (`git diff`); `staged = true`
returns the index-vs-HEAD diff (`git diff --cached`). Path traversal
(`..`, absolute paths) is rejected before invoking git.

```jsonc
// daemon → client
{
  "type": "git_diff_result",
  "project_id": "<uuid>",
  "path": "src/lib.rs",
  "staged": false,
  "patch": "diff --git a/src/lib.rs b/src/lib.rs\n@@ -1 +1 @@\n-old\n+new\n"
}
```

The patch is the raw `git diff` text (color-disabled with `--no-color`).
The frontend parses it line-by-line for syntax-coloring; the daemon does
not pre-render.

### Errors

```jsonc
{
  "type": "git_error",
  "project_id": "<uuid>",
  "message": "git: not on PATH"
}
```

### `GitCommit`, `GitPull`, `GitPush`

```jsonc
// client → daemon
{ "type": "git_commit", "project_id": "<uuid>", "message": "Ship the sidebar actions" }
{ "type": "git_pull", "project_id": "<uuid>" }
{ "type": "git_push", "project_id": "<uuid>" }
```

`git_commit` commits **staged changes only** with `git commit -m <message>`.
`git_pull` runs `git pull --ff-only`. `git_push` runs `git push`.

```jsonc
// daemon → client (success)
{
  "type": "git_action_result",
  "project_id": "<uuid>",
  "action": "commit",
  "message": "[main abc1234] Ship the sidebar actions"
}
```

```jsonc
// daemon → client (failure)
{
  "type": "git_action_error",
  "project_id": "<uuid>",
  "action": "pull",
  "message": "fatal: Not possible to fast-forward, aborting."
}
```

### `GitStage`, `GitUnstage`

```jsonc
// client → daemon
{ "type": "git_stage", "project_id": "<uuid>", "paths": ["src/lib.rs", "README.md"] }
{ "type": "git_unstage", "project_id": "<uuid>", "paths": ["src/lib.rs"] }
```

`git_stage` runs `git add -- <paths...>`. `git_unstage` runs
`git restore --staged -- <paths...>`.

Both operations answer with the same `git_action_result` /
`git_action_error` envelope used by commit/pull/push, with `action`
set to `stage` or `unstage`.

## Multi-node behavior

When the project's `node_id` points at a peer other than the daemon
receiving the request, the daemon forwards the message over the inter-node
WebSocket (mirroring `ListOsUsers` / `GetDaemonLog` / `ListProjectFiles`)
and relays the peer's reply back. The client sees a single response.

## Run-as-user

When the project has a `run_as_users` entry for the local node, every git
command the panel runs (status, diff, commit, pull, push, stage, unstage) is
wrapped in the same shim used for session
spawns (`runuser --session-command` on Unix, the `clusto-runas.exe` helper
on Windows). This means the user's `~/.gitconfig`, credentials, hooks, and
gitignore behave exactly as they do in their own shell.

## Caching and invalidation

* Status is cached per project. A new `git_status_result` invalidates **all**
  cached diffs for that project (the working tree may have moved); the diff you
  have open is re-fetched so it does not go blank.
* Diffs are cached per `(project, path, staged-flag)` triple. Invalidated by
  a new status push or explicit project reset.

## Limitations

* Commit still includes the current staged set only. If you need to commit a
  subset, first select those files and use `Stage selected` / `Unstage selected`
  so the index matches exactly what you want to commit.
* Commits and checkouts made outside the app show on the next window focus or
  manual refresh, because the file watcher skips `.git`.
* `Pull` is fast-forward only. Non-fast-forward updates still need to be
  resolved in a terminal or external Git client.
* The diff viewer uses a plain `<pre>` with class-based coloring, not
  CodeMirror's merge view - keeping the panel lightweight.
