Hi,
For years, developers using Seafile have tried to sync active software repositories across machines by storing working directories directly inside synced libraries. As many of us have experienced firsthand, this causes severe friction:
-
Sync Client Thrashing: A single
git committouches 15+ files inside.git/in milliseconds, triggering hundreds of continuous library re-index cycles per day (over 1,500+ cycles/day observed in active repos). -
Lock Contention: Ephemeral lock files like
.git/index.locksync across machines, freezing Git operations on secondary computers. -
Conflict Storms: Diverging branches cause Seafile to generate hundreds of
(SFConflict ...)duplicate files rather than allowing Git to perform 3-way line merges. -
Ignore Limitations:
.seafile-ignore.txtcannot ignore folders retroactively, must sit at library root, and amputates.git/from secondary machines if used.
To solve this properly without requiring developers to deploy and maintain a separate Git server stack (like GitLab or Gitea), I have built git-remote-seafile—a transparent, zero-thrash Git remote helper for Seafile.
-
Architecture & Design Spec: git-remote-seafile/DESIGN.md at main · tkittich/git-remote-seafile · GitHub
-
User’s Guide: git-remote-seafile/USER_GUIDE.md at main · tkittich/git-remote-seafile · GitHub
How It Works
Instead of placing local working repositories inside synced folders, developers keep their code in normal un-synced folders (e.g. C:\code\myproject or ~/code/myproject).
git-remote-seafile implements the official git-remote-helpers(7) protocol and speaks directly to the Seafile Web API v2.1 over HTTP/HTTPS:
# Push directly to any Seafile library as an authentic Git remote:
git remote add origin seafile://code/myproject
git push -u origin main
# Clone on another workstation:
git clone seafile://seafile.example.com/code/myproject
Key Capabilities & Guarantees
-
Atomic Packfile Transport: Commits are bundled into native Git packfiles (
.packand.idx) before upload. Pushing 100 commits uploads only 1–2 files, resulting in sub-second pushes (<1s) and zero desktop daemon scanning. -
Fast-Forward Safety & Conflict Elimination: Non-fast-forward pushes are rejected unless force-pushed. Standard Git pull/rebase handles merging; no
(SFConflict ...)files can ever be generated. -
Distributed Lease Locking: Pushes acquire an advisory lease on
.git-lock.jsonon Seafile with auto-expiration (60s), preventing race conditions without risk of deadlocks from crashed clients. -
Git LFS Integration: Implements the official Git LFS Custom Transfer Agent protocol (
lfs-transfer), allowing multi-gigabyte models, datasets, or video assets to stream into Seafile storage. -
Remote Packfile Compaction & Auto-GC (
gc): Re-packs accumulated remote packs, delta-compresses history, and automatically prunes unreachable commits from rolled-back branches. -
Zero-Config Auth: Automatically detects active logins from Windows, macOS, Linux, and
seaf-clilocal desktop client SQLite databases (accounts.db), or falls back to~/.git-seafile.json/ environment variables. -
Production-Grade Test Suite: Includes 38 automated unit tests with full CI across Windows, Linux, and macOS (Python 3.8–3.14).
Proposal to Haiwen / Upstream Integration
I would love to upstream this project into the official Seafile ecosystem:
-
Host under the official organization as
haiwen/git-remote-seafile(or bundle within the client distribution). -
Distribute via PyPI and package with Seafile desktop installers.
-
Integrate a context-menu option in the Seafile desktop client (“Copy Git Remote URL”, patch ready in repo).
Feedback, suggestions, and thoughts from the maintainers and community are warmly welcome!