How silvanocerza/github-gitless-sync works
Project type and purpose
• This is an Obsidian community plugin (“GitHub Gitless Sync”) that synchronizes a local Obsidian vault with a GitHub repository purely via REST calls—no git executable.
• Its core use case: bidirectional sync (push/pull) between multiple vaults and GitHub, with automatic/manual triggers and built-in conflict resolution UI.
File structure
• Top-level:
• manifest.json / manifest-beta.json → plugin metadata for Obsidian
• esbuild.config.mjs, version-bump.mjs → build & release pipeline
• assets → screenshots used in README/settings
• src → all TypeScript source code
• src subfolders:
• github → HTTP client for GitHub REST API
• settings → configuration UI & storage
• views → React/TSX components for conflict-resolution views (split/unified)
• utilities: logger.ts, utils.ts
• core orchestration: main.ts, events-listener.ts, sync-manager.ts, metadata-store.ts
• Configuration & metadata: package.json, tsconfig.json, versions.json.
README insights
• Describes plugin features, UI screens, token requirements, first-sync constraints, conflict-resolution modes, config-folder sync, and reset workflow.
• Emphasizes mobile/desktop support via same logic, and reliance on GitHub REST APIs over git.
a. Main components to include:
• Obsidian Host (Electron or Mobile runtime)
• Plugin Entry & Event Listener (main.ts + events-listener.ts)
• Settings Module (src/settings)
• Sync Manager (src/sync-manager.ts)
• Metadata Store (src/metadata-store.ts)
• GitHub Client (src/github/client.ts)
• Local Vault File System (Obsidian vault folder)
• Conflict Resolution UI (src/views/conflicts-resolution)
• Logger & Utilities
• Build Pipeline (esbuild, version bump scripts)
• External Service: GitHub REST API
b. Relationships & interactions:
1. User triggers sync via UI ribbon/button → Event Listener
2. Event Listener invokes Sync Manager
3. Sync Manager consults Metadata Store to determine changed files
4. For remote operations, Sync Manager calls GitHub Client → GitHub REST API
5. For local operations, Sync Manager reads/writes vault files via Obsidian file API
6. If conflicts arise, Sync Manager launches Conflict Resolution UI (split/unified)
7. User resolves conflicts in UI → Sync Manager finalizes resolution and updates Metadata Store
8. Settings Module supplies config (token, repo, branch) to Sync Manager
9. Logger captures events at each stage
c. Architectural patterns/design principles:
• Modular separation: core orchestration vs. UI vs. HTTP client vs. storage
• Event-driven: Obsidian plugin lifecycle & command registration
• MVC-style within plugin:
• Model = Metadata Store + Settings
• View = Conflict Resolution React components
• Controller = Sync Manager + Event Listener
• Single-responsibility: each TS file handles a discrete function
• Build-time bundling via esbuild ensures a lightweight plugin deliverable
d. Key technologies/frameworks:
• Obsidian Plugin API (TypeScript)
• React/TSX for in-vault UI
• esbuild for bundling
• GitHub REST API (via custom client)
• PNPM / npm for dependency management
Be detailed but concise
• Every logical piece: plugin entry, settings, sync logic, storage, UI, external API
• Avoid over-splitting: group helpers (logger, utils) under “Utilities” unless they’re central