nautilus-gitscm

A lightweight Git client integration for the GNOME Nautilus file manager, inspired by RabbitVCS / Rabbit SCM Git.

Features

File status emblems

Emblem	Meaning
🟢 green checkmark	File is tracked by Git and up-to-date
🔴 red cross	File is tracked by Git and has local changes (staged or unstaged)
⚫ grey question mark	File is inside a Git repository but not tracked (untracked)

Emblems are shown directly on the file/folder icons in Nautilus so you can see the Git state of every item at a glance.

Context menu Git actions (right-click)

Action	When visible
Git Pull / Update	Repository has at least one configured remote
Git Commit…	Selected files have staged, unstaged, or new changes
Git Push	Current branch is ahead of its upstream (unpushed commits exist)
Git Commit History	Exactly one tracked file is selected

Pull / Update, Commit…, and Push open a terminal window to show command output. Git Commit History opens a dedicated GUI window (no terminal) with a scrollable, monospace view of the git log for the selected file.

---

Requirements

Package	Purpose
python3-nautilus (Ubuntu/Debian) / nautilus-python (Fedora/RHEL) / python-nautilus (Arch)	Nautilus Python extension bindings
git	Git CLI
gnome-terminal / xterm / konsole / …	Terminal for action output

Install the bindings if missing:

# Ubuntu / Debian / Linux Mint
sudo apt install python3-nautilus

# Fedora / RHEL
sudo dnf install nautilus-python

# Arch Linux
sudo pacman -S python-nautilus

Required on Fedora: install nautilus-python first.
Without Nautilus Python bindings, this extension will not load at all (no emblems, no Git context menu entries, no extension debug logs).

---

Installation

Fedora / RHEL (recommended explicit flow)

sudo dnf install nautilus-python git
git clone https://github.com/toherrmann/gitscm.git
cd gitscm
bash install.sh
nautilus -q && nautilus &

Generic

git clone https://github.com/toherrmann/gitscm.git
cd gitscm
bash install.sh

Then restart Nautilus:

nautilus -q && nautilus &

Tip: If emblems do not appear immediately, try logging out and back in so the GTK icon cache is fully refreshed.

Debugging on Fedora / GNOME

The extension is quiet by default. To enable verbose diagnostics:

GITSCM_DEBUG=1 nautilus -q
GITSCM_DEBUG=1 nautilus

Then inspect logs:

journalctl --user -f | grep -Ei 'gitscm|nautilus'

If the extension is loaded, you should see gitscm: log lines showing extension load information and reasons why emblems or menu entries are skipped.

Important: org.gnome.NautilusPreviewer / WebKit2 errors come from the Nautilus Previewer (GNOME Sushi) component, not from this extension.

Troubleshooting: extension appears not to load

Symptoms:

• no emblems shown
• no Git context menu entries shown
• no gitscm: debug logs visible

First check (especially on Fedora):

rpm -q nautilus-python

If it is missing, install it and restart Nautilus:

sudo dnf install nautilus-python
nautilus -q && nautilus &

Then retry with debug enabled:

GITSCM_DEBUG=1 nautilus -q
GITSCM_DEBUG=1 nautilus
journalctl --user -f | grep -Ei 'gitscm|nautilus'

What install.sh does

1. Copies nautilus-gitscm/nautilus_gitscm.py → ~/.local/share/nautilus-python/extensions/
2. Copies the SVG emblem icons → ~/.local/share/icons/hicolor/scalable/emblems/
3. Runs gtk-update-icon-cache to register the new icons

---

Uninstallation

bash uninstall.sh
nautilus -q && nautilus &

---

Repository structure

nautilus-gitscm/
├── nautilus_gitscm.py          # Main Nautilus extension (Python 3)
└── icons/
    ├── emblem-gitscm-clean.svg      # Green checkmark
    ├── emblem-gitscm-modified.svg   # Red cross
    └── emblem-gitscm-untracked.svg  # Grey question mark
install.sh                      # User-local installation script
uninstall.sh                    # Removal script
README.md

---

How it works

The extension registers two Nautilus interfaces:

• Nautilus.InfoProvider — called for every visible file/folder.
  Runs git rev-parse --show-toplevel (cached per directory) to detect whether an item is inside a repository, then git status --porcelain to determine the emblem to attach.

• Nautilus.MenuProvider — called when the user right-clicks.
  Checks repository state (git remote, git status, git rev-list @{u}..HEAD) to decide which menu entries to display, then opens a terminal window to execute the chosen Git command (Pull / Update, Commit, Push) or a dedicated GTK GUI window for Git Commit History.

Git repository root lookups are cached in memory to avoid redundant subprocess calls while browsing large directories.

---

License

MIT