Skip to content
Míng hàn edited this page Nov 7, 2026 · 2 revisions

Usage

This page explains how to open repositories, navigate the commit tree, and customize git-tree.


Opening a repository

When git-tree starts, the home screen has four tabs.

[ LOCAL FOLDER ] — open a repo on your computer

  1. Select the [ LOCAL FOLDER ] tab.
  2. Type the full path to the repository (e.g. /home/you/projects/my-app), or click 📁 to pick a folder.
  3. Click OPEN →.

Your last 5 opened repositories appear under the input for quick access.

[ REMOTE URL ] — clone from GitHub / GitLab

  1. Select the [ REMOTE URL ] tab.
  2. Paste a repository URL, e.g. https://github.com/user/repo.
  3. Click CLONE →.

The repo is shallow-cloned into a temporary folder and opened automatically. Click [ CANCEL ] to stop a clone that is taking too long.

[ SEARCH ONLINE ] — search GitHub

  1. Select the [ SEARCH ONLINE ] tab.
  2. Type a query (e.g. rust async runtime).
  3. Press Enter or click SEARCH →.
  4. Click CLONE → on any result to open it.

[ MY REPOS ] — your own GitHub repositories

  1. Click [ SIGN IN WITH GITHUB ].
  2. git-tree shows a short code. Open the GitHub link it gives you, enter the code, and approve.
  3. Your repositories appear in a list you can sort by Updated, Stars or Name.
  4. Click any repo to clone and open it.

Click [ SIGN OUT ] to remove the saved login.


The tree view

After a repo loads you see three areas:

Area What it shows
Left panel Details of the selected commit: hash, author, date, message, branches
Center The commit tree, plus a minimap for jumping around large histories
Right panel Diff stats for the selected commit: files changed, additions, deletions

Mouse

  • Click a commit node to select it and show its details.
  • Drag to pan the tree.
  • Ctrl + scroll to zoom.
  • Click the minimap to jump to that region.

Toolbar

Button Action
Search box Filter commits by author, message or hash
[ REFRESH ] Reload the repository
[ STATS ] Open repository statistics
[ EXPORT ] Save the tree as an SVG image
[ SETTINGS ] Open settings
[ ? ] Show keyboard shortcuts

With a commit selected, open the full diff viewer with d. Files in the diff can be collapsed and expanded.


Keyboard shortcuts

Press ? at any time to see this list inside the app.

Navigation

Key Action
→ / l Next commit (horizontal tree)
← / h Previous commit (horizontal tree)
↓ / j Next commit (vertical tree)
↑ / k Previous commit (vertical tree)
Esc Deselect commit / go back to the tree / close the help

View

Key Action
+ Zoom in
- Zoom out
0 Reset zoom and pan
[ Toggle left panel
] Toggle right panel

Screens & actions

Key Action
/ Focus the search box
d Open the diff of the selected commit
s Open stats
, Open settings
e Export the tree as SVG
? Toggle the shortcuts help

Shortcuts work only on the tree screen, and not while you're typing in a text field.


Statistics

Press s or click [ STATS ] to see:

  • Contributors: who committed the most
  • Activity heatmap: when commits happened

Press Esc to go back to the tree.


Settings

Press , or click [ SETTINGS ]. Changes apply immediately and are saved automatically.

UI style

  • Terminal: retro terminal look
  • Modern: cleaner, modern look

Theme

15 built-in themes with live preview:

Terminal · Matrix · Amber · Synthwave · Nord · Dracula · Gruvbox · Blood Moon · Ice Terminal · Light · Dark · Tokyo Night · Cappuccino Mocha · Rose Pine · Everforest

Display

Setting Options
Font size Slider
Node spacing Compact · Normal · Wide
CRT scanlines On / Off (retro screen overlay)

Tree

Setting Options
Merge commits Show / Hide
Tree direction Horizontal / Vertical
Branch style Curved (smooth bezier) / Geometric (flat-top steps)

The About section shows your installed version. git-tree checks GitHub for new releases on startup and lets you know when an update is available.


Exporting

Press e or click [ EXPORT ], choose where to save, and git-tree writes the current tree as git-tree-export.svg. You can open it in a browser, Inkscape or Figma, or embed it in docs.


Opening commits on GitHub / GitLab

For repos with a GitHub or GitLab remote, the commit details panel has a link that opens the selected commit in your browser.


Where git-tree stores data

File Contents
~/.config/git-tree/settings.toml Your settings (theme, style, font size, …)
~/.config/git-tree/recent.json Last 5 opened repositories
~/.config/git-tree/token.json GitHub login token (only if you signed in)
~/.local/share/git-tree/ WebView data

On Windows, these live under %APPDATA%\git-tree\.

To reset git-tree to defaults, close it and delete ~/.config/git-tree/.


See also

  • NixOS: installing and troubleshooting on NixOS
  • Issues: report bugs or request features