Skip to content

Troubleshooting

MΓ­ng hΓ n edited this page May 12, 2026 · 1 revision

❗ Troubleshooting

This page contains common issues and fixes for git-tree.


🐧 Linux Issues

⚠️ Missing libxdo.so.3

Error

error while loading shared libraries: libxdo.so.3: cannot open shared object file

Cause

Some Linux distributions (especially Arch Linux) only provide:

libxdo.so.4

while the binary expects:

libxdo.so.3

Fix

Create a compatibility symlink:

sudo ln -s /usr/lib/libxdo.so.4 /usr/lib/libxdo.so.3

Then try running git-tree again.


πŸ“¦ AppImage Does Not Launch

Symptoms

  • Nothing happens when opening AppImage
  • AppImage closes immediately
  • GTK/WebKit errors appear

Fix

Install required dependencies.

Arch Linux

sudo pacman -S webkit2gtk-4.1 gtk3 libgit2 xdotool

Ubuntu / Debian

sudo apt install \
  libwebkit2gtk-4.1-dev \
  libgtk-3-dev \
  libgit2-dev \
  libxdo-dev

Fedora

sudo dnf install \
  webkit2gtk4.1-devel \
  gtk3-devel \
  libgit2-devel

πŸ”’ Permission Denied

Error

Permission denied

Fix

Make the binary executable:

chmod +x git-tree-linux-x86_64

or for AppImage:

chmod +x git-tree-*.AppImage

🌐 Git Clone Fails

Possible Causes

  • No internet connection
  • Invalid repository URL
  • Private repository access denied

Fixes

  • Verify internet connection
  • Double-check repository URL
  • Ensure repository is public
  • Try cloning manually with Git first

Example:

git clone https://github.com/user/repo.git

πŸ–₯️ UI Appears Blank

Cause

Usually related to missing GTK/WebKit libraries.


Fix

Install required dependencies for your distribution.

See:

πŸ‘‰ [Linux Compatibility](https://github.com/MahiroJV/git-tree/wiki/Linux-Compatibility)


🧠 Performance Issues

Large Repositories

Very large repositories may cause:

  • slower rendering
  • increased memory usage
  • delayed zoom/pan response

Recommendations

  • Use vertical tree layout
  • Disable merge commit visibility
  • Reduce node spacing
  • Close other heavy applications

πŸ”„ Installer Script Fails

Cause

Usually caused by:

  • missing curl
  • unsupported distro
  • network issues

Fix

Install curl manually:

Arch Linux

sudo pacman -S curl

Ubuntu / Debian

sudo apt install curl

Fedora

sudo dnf install curl

Then retry:

curl -fsSL https://raw.githubusercontent.com/MahiroJV/git-tree/master/install.sh | bash

❓ Still Need Help?

If your issue is not listed here:

  • Open a GitHub issue
  • Include your Linux distribution
  • Include the full error message
  • Include terminal output if possible

πŸ‘‰ https://github.com/MahiroJV/git-tree/issues