Skip to main content

GitTreeDesk — User Guide & Feature Reference

Status: ✅ Implemented — every page describes behavior that ships in the v1 build. English is canonical. The Chinese translation is the docs site's zh-Hans locale (website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/), kept in sync file for file. Engineering reference: ../spec.md (architecture, key decisions, performance budgets).

How this guide drives development​

This folder is both the user manual and the development backlog. The workflow:

  1. Edit the page covering the feature you want (or add a section / a new page).
  2. Ask the AI: "implement <page> § <section>".
  3. The AI implements it, verifies the behavior, and updates that page's Status line.

Rules for edits:

  • Write intended behavior in the present tense, as the finished product behaves: "Clicking X opens Y."
  • Defaults, interactions, error messages, and edge cases are part of the requirement — include or change them explicitly.
  • Mark post-v1 ideas inline with [Later].
  • If an edit contradicts ../spec.md, the AI must flag the conflict and propose a spec update instead of silently diverging.
  • Code comments, identifiers, and commit messages never cite document numbering (F4, AD-12, page numbers). These documents are transitional and may be deleted once the behavior ships, which would leave unresolvable references in the code history — describe the behavior instead ("stage a single hunk from the diff view", not "per F7").
  • Edit whichever language is more comfortable; the AI keeps the other version in sync.

Status legend: 🚧 Planned · 🔨 In progress · ✅ Implemented

What is GitTreeDesk​

A workspace-first multi-repo Git workbench. Open any folder — it does not need to be a Git repository — and manage every Git repository, worktree, and submodule inside it from one tree: full Git operations, a per-repository commit graph, file browsing with diffs and light editing, and integrated terminals. It is deliberately not a general-purpose IDE; where deeper code intelligence is needed, a one-click "Open in VSCode" escape hatch is provided.

Prerequisites​

Git≥ 2.23 required (≥ 2.36 recommended). Read from PATH; can be overridden in settings. A warning appears if the version is too old or Git is missing.
OSWindows 10+ · macOS 11+ · Linux (AppImage / deb)

Getting started​

  1. Install GitTreeDesk for your platform (installer, or portable zip on Windows).
  2. First launch shows the Welcome screen: recent workspaces, "Open folder…", and a drop zone — you can also drag a folder onto the window.
  3. Open a workspace root. Any folder works; it does not need to be a Git repository. Example: E:\Projects\acme.
  4. Trust prompt. The first time a workspace is opened, a prompt asks whether you trust it — once per workspace root. Until trusted, GitTreeDesk suppresses Git hooks (core.hooksPath override) and disables workspace-defined terminal quick commands. Trust is remembered per workspace root; you can change it later via the command palette ("Trust This Workspace" / "Revoke Trust").
  5. Repositories appear progressively. The tree fills in once discovery finishes, then statuses and badges land incrementally as the background refresh walks the repositories (see page 01).

The window at a glance​

┌ Titlebar: workspace name · window controls ─────────────────────────────┐
│ Activity │ Primary sidebar           │ Editor area (tabs)              │
│ bar      │  ▸ Explorer               │  • file  • diff  • graph        │
│  Tree    │  ▸ Repos                  │  • settings  • keyboard refs    │
│  SCM     │  ▸ Source Control         │                                 │
│  Graph   │  ▸ Graph                  ├─────────────────────────────────┤
│  ⚙       │                           │ Secondary sidebar: details      │
│          │                           │ (commit, file, repo) — toggle   │
├──────────┴───────────────────────────┴─────────────────────────────────┤
│ Bottom panel: Terminal │ Output (Git operation logs)   — collapsible   │
├─────────────────────────────────────────────────────────────────────────┤
│ Status bar: workspace · branch · ↓↑ · theme · language · git version   │
└─────────────────────────────────────────────────────────────────────────┘
  • Activity bar switches the sidebar between Tree, Source Control, Graph, and Settings; the terminal lives in the bottom panel.
  • The status bar shows the workspace name, the active repository's branch and ahead/behind counts, the theme, the language, and the Git version — clicking the branch opens the repo/branch picker.
  • Everything is reachable from the command palette (Ctrl/Cmd+Shift+P) and has a default shortcut (page 12).

Five-minute tour​

  1. Open your workspace and switch the sidebar to Tree.
  2. In the Repos view, find a repository with a ● badge (uncommitted changes) and click it.
  3. The Source Control view shows its changes — click a file to see the diff, stage files (or single hunks), type a commit message (or press the ✨ generate button), and Commit.
  4. Open the Graph tab for that repository; right-click your new commit — branches, tags, cherry-pick, revert, and more live there.
  5. Press Ctrl+` to open a terminal at the repository root and run your usual commands.

Page index​

#PageCoversStatus
—01 Workspace & TreeOpening workspaces, repository discovery, trust, Explorer & Repos views, badges, filters✅
—02 WorktreesDisplay, create, move, remove, prune, lock — worktrees as first-class citizens✅
—03 Changes & DiffMulti-repo changes list, staging, discarding, diff viewer, file history✅
—04 Commit & MessagesCommit, amend, history rewrite (message/author/date), commit message generation (offline + LLM)✅
—05 Branches, Remotes & TagsBranch operations, remotes, fetch/pull/push, tags, batch operations✅
—06 Merge, Rebase & ConflictsMerge, rebase (incl. interactive), cherry-pick, revert, reset, conflict resolution, safety nets✅
—07 StashCreating, listing, applying and dropping stashes✅
—08 SubmodulesSubmodule display, status, one-click update, sync✅
—09 Commit GraphPer-repo commit graph, workspace activity timeline, filters, commit actions, large-repo handling✅
—10 EditorFile viewing and light editing, TypeScript hints, diffs, Open in VSCode✅
—11 TerminalShell profiles, per-directory cascading config, quick commands✅
—12 Settings & KeyboardSettings UI, config files, default shortcuts, command palette, keymap customization✅
—13 FAQ & TroubleshootingCommon problems, recovery procedures, how to request features✅