Git workflows | Ghostex Docs

Git menu structure

The sidebar Git split button exposes three sections. The titlebar Git button runs the primary action on click and shows the full flat menu on right-click.

Option	What it does
`Direct Actions`	Commit, Push, View PR (when an open PR exists)
`Agent Workflows`	Create PR, Sync with Main (worktree only), Multicommit & Release, Release
`Toggles`	Review Commit Title, Generate commit body

Titlebar tooltip: Commit. Right-click for more actions. Titlebar clicks always force the commit review modal when changes exist.

Direct vs agent workflows

Option	What it does
`commit / push`	Direct gxserver git — optional review modal
`View PR`	Direct gh pr view — opens PR URL in browser pane
`Create PR`	Agent terminal with PR prompt (no open PR)
`Sync with Main`	Agent terminal — worktree projects only
`Multicommit & Release`	Agent terminal — multiple commits then release
`Release`	Agent terminal — version bump and publish
`Multiple Commits`	Agent terminal — from commit modal footer

Agent workflows use Settings → Default Prompt Agent (or the commit modal footer override). They intentionally skip persistent running toasts — the agent terminal is the progress surface.

Commit review modal

The Git Commit modal (1020×760) opens when review is required or forced. Draft state is keyed by requestId so unrelated session updates do not reset in-progress edits.

Left pane — changed-files tree, optional commit message, per-file include/exclude checkboxes.
Right pane — inline diff (file or Show All), unified/split toggle, line wrap, hide whitespace.
Footer — Cancel, Merge to main (worktrees), Commit on new branch, Multiple Commits, primary confirm.
Footer prompt-agent dropdown — per-modal override stored as ghostex.promptAgent.gitCommit.
Diff preferences persist in localStorage ghostex.gitCommitModal.diffPreferences.v1.

Review triggers:

Any worktree project — always review before commit, push, or PR.
Titlebar Git click — forceCommitReview always true.
Dirty tree + Review Commit Title toggle enabled (gitConfirmCommit).

Confirm labels

Option	What it does
`Commit`	Commit action with staged changes
`Commit & Push`	Push action with uncommitted changes
`Push`	Push only — no local changes
`Commit, Push & PR`	PR action with uncommitted changes
`Push & Create PR`	PR action — commits already pushed
`View PR`	Open existing PR when one is already open
`Push & View PR`	Push then open existing PR

Sync with Main

Sync with Main appears only for worktree projects (isWorktree === true). It launches an agent session titled Git: Sync with Main.

Agent fetches latest refs and merges or rebases main into the worktree branch per repo convention.
Prompt preserves both sides and resolves conflicts, leaving the branch ready to merge back.
Does not require GitHub CLI.
Non-worktree projects show toast: Worktree unavailable — Open a worktree project to sync with main.

Git preferences

Git action preferences live in the Git dropdown footer toggles, not the main Settings page. Values sync to gxserver gitConfig.

Option	What it does
`Review Commit Title (gitConfirmCommit)`	Open review modal before direct commit/push when tree is dirty (default: off). Stored in ghostex-native-git-confirm-commit.
`Generate commit body`	Ask prompt agent for commit body in addition to title (default: on). Stored in ghostex-native-git-generate-commit-body.
`primaryAction`	commit \| push \| pr — titlebar primary button target. Persisted in ghostex-native-git-primary-action.

Settings → Default Prompt Agent drives Git helper prompts, project board Start Work, and worktree first-prompt defaults.

Toasts

Option	What it does
`Committing / Commit complete`	Direct commit with persistent running toast
`Pushing / Push complete`	Direct push (with or without prior commit)
`PR flow complete`	Direct PR view or create
`Merging worktree into main`	Direct merge from commit modal
`Deleting worktree`	Worktree delete workflow
`(none)`	Agent workflows — terminal is progress; no duplicate running toast

Running toasts use a spinner (ghostex-app-toast-persistent) and finish with success, warning, or error tint on the same toastId.

Disabled reasons

Git action already running.
No working tree changes to commit.
Branch is behind upstream. Pull or rebase first.
Install GitHub CLI (gh) for PR actions.
Open a worktree project to sync with main.
Agent unavailable / Could not open {agent} for agent workflows.

Other modals

Option	What it does
`Git Commit (review)`	1020×760 — primary review workspace
`Git File Diff`	1180×820 — standalone diff when not embedded
`Delete Worktree`	Status summary, Commit shortcut, branch delete options

Dirty worktree delete modal exposes a Commit button that opens commit review with forceCommitReview: true.

Tips

Enable Review Commit Title if you want suggested messages but still approve before push.
Use titlebar Git for quick review-first commits; use sidebar chevron when you need agent workflows.
Worktree Merge to main in the commit modal is the direct path — Create PR is the agent path with optional delete-after.
Git operations run through the desktop app → gxserver HTTP API — there are no ghostex CLI git commands.
Leave Generate commit body on for richer commit messages from your Default Prompt Agent.

Related docs

Worktrees

Embedded code editor

Projects & sidebar

Command palette & hotkeys