Professional Obsidian-GitHub Sync Tool
Ogresync is a professional-grade open source desktop application that seamlessly synchronizes your Obsidian notes across devices. Mimics the Obsidian Sync feature for free by using GitHub. Built with enterprise-level reliability, cross-platform compatibility, and intelligent conflict resolution systems.
Before using Ogresync, please ensure you have the following installed:
1. Obsidian
- Download from: https://obsidian.md/download
- Install and run Obsidian
- Create a vault folder where you want to store your notes
2. Git
- Download from: https://git-scm.com/downloads
- For new users: Run the setup file and click "Next" until you reach "Setup Completed" for standard Git installation
- Git is required for repository synchronization
| Platform | Download | Status |
|---|---|---|
| Windows | Download from Releases | Available |
| Linux | Download from Releases | Available |
| macOS | Ogresync.app |
Coming in future updates |
Windows:
- Download
ogresync.exe - You may need to allow the file if your antivirus flags it as a threat
- Run the executable
Linux:
- Download
ogresync.AppImage - Make it executable:
chmod +x ogresync.AppImage - Run:
./ogresync.AppImage
Important
Ogresync fundamentally changes how you interact with Obsidian by becoming the central orchestrator for all your note-taking activities. Instead of opening Obsidian directly, you launch Ogresync, which then handles the entire synchronization workflow seamlessly.
This is the heart of Ogresync - understanding this workflow is crucial:
- Launch Ogresync (not Obsidian) - This is your new workflow
- Ogresync performs intelligent pre-sync - Checks for remote changes, handles conflicts
- Ogresync launches Obsidian automatically - With your vault already synchronized
- Edit your notes freely - Work normally in Obsidian without sync worries
- Close Obsidian when finished - Ogresync detects closure immediately
- Ogresync handles post-sync - Commits your changes, pushes to GitHub, handles any new conflicts
This workflow ensures your vault is always in perfect sync before and after editing, with intelligent conflict resolution at every step.
Traditional Approach Problems:
- Opening Obsidian directly can lead to sync conflicts
- Manual git operations are error-prone
- No visibility into sync status during editing
- Conflicts discovered only after making changes
Ogresync's Solution:
- Pre-sync verification ensures clean starting state
- Active monitoring tracks changes during editing
- Automatic conflict detection before they become problems
- Intelligent post-processing handles any edge cases
The result: A worry-free editing experience where synchronization happens invisibly and reliably.
On first launch, Ogresync runs in Setup Mode with an 11-step wizard that guides you through:
- Obsidian Checkup - Verify Obsidian installation
- Git Check - Verify Git installation
- Choose Vault - Select your Obsidian vault folder
- Initialize Git - Setup Git repository in your vault
- SSH Key Setup - Generate or verify SSH key for GitHub
- Known Hosts - Add GitHub to trusted hosts
- Test SSH - Test SSH connection to GitHub
- GitHub Repository - Link your GitHub repository
- Repository Sync - Enhanced two-stage conflict resolution
- Final Sync - Intelligent synchronization with safeguards
- Complete Setup - Finalize configuration
Once setup is complete, a configuration file is stored in OS-specific locations:
- Windows:
%APPDATA%\Ogresync\ - Linux:
~/.config/ogresync/
To run setup again, delete the configuration file and restart the application.
After Setup - Sync Mode: Once setup is complete, Ogresync switches to Sync Mode which follows the core workflow described above. Every time you want to use Obsidian, simply launch Ogresync instead.
- Real-time vault monitoring during Obsidian sessions
- Bidirectional sync with GitHub
- Automatic conflict detection and resolution
- Smart merge algorithms with git history preservation
- Stage 1: High-level strategy selection (Smart Merge, Keep Local, Keep Remote)
- Stage 2: File-by-file resolution for complex conflicts
- Automatic local backups created before any changes
- Complete version history preservation through Git
- Rollback capabilities to any previous state
- Graceful handling of concurrent editing scenarios
- No constant internet required
- Smart offline state management and session tracking
- Automatic sync when internet becomes available
- Seamless transition between online and offline modes
- Conflict resolution triggered only when transitioning offline-to-online
- Comprehensive backup system with descriptive naming
- Data integrity verification
- Extensive edge case handling
- Thoroughly tested for reliability
- Non-destructive operations that preserve git history
- Pre-sync Phase: Automatically checks for remote changes before opening Obsidian
- Session Monitoring: Tracks remote changes that occur during your editing session
- Post-sync Phase: Intelligently handles conflicts that emerge during your session
- Recovery Operations: Automatic detection and handling of interrupted sync operations
- Complex git operations simplified for users without git knowledge
- Intelligent handling of merge conflicts, rebases, and unpushed commits
- Automatic upstream tracking configuration
- Smart detection of recovery scenarios and conflict resolution needs
- Force-push protection with user consent for critical operations
- Native support for Windows and Linux (macOS coming soon)
- Handles various Obsidian installation methods (native, Snap, Flatpak, AppImage)
- Platform-optimized file operations and process management
- OS-specific configuration storage
Ogresync is perfect for:
Individual Users:
- Dual-boot systems: Access your vault from different OS installations
- Cloud backup: Secure your notes with Git's powerful version control
- Version history: Rollback to any previous version of your notes
Teams and Collaboration:
- Concurrent editing: Multiple users working on the same vault simultaneously
- Team documentation: Collaborative knowledge bases
- Research groups: Shared research notes and findings
Professional Applications:
- Company wikis: Internal documentation management
- Student collaboration: Shared study materials
- Writing projects: Manuscript backup and version control
The 11-step setup wizard is designed to be user-friendly even without Git knowledge:
- Obsidian Detection: Automatically finds your Obsidian installation
- Git Verification: Ensures Git is properly installed and configured
- Vault Selection: Choose your existing vault or create a new one
- Git Setup: Initialize repository in your vault and create initial commit
- SSH Key Generation: Creates secure SSH keys for GitHub authentication
- GitHub Setup: Configures secure connection to GitHub servers
- Connection Testing: Verifies everything works properly before proceeding
- Repository Linking: Connects your local vault to GitHub repository
- Enhanced Conflict Resolution: Uses two-stage system if both local and remote have content
- Final Sync: Completes setup with intelligent synchronization
- Configuration: Saves all settings for future sync sessions
What happens during Repository Sync (Step 9):
The wizard analyzes your repository state and handles four scenarios:
- Both Empty: Creates initial README and prepares for first sync
- Local Empty, Remote Has Files: Simple pull operation to get remote content
- Local Has Files, Remote Empty: Prepares local files for push to GitHub
- Both Have Files: Triggers enhanced two-stage conflict resolution
When both repositories contain files, Ogresync automatically detects conflicts and launches the two-stage resolution system, ensuring safe merging of your content with complete history preservation.
Each step provides clear guidance and error recovery options.
Ogresync is built with a modular, dependency-injection architecture:
| Module | Purpose |
|---|---|
Ogresync.py |
Main application entry point and module orchestration |
setup_wizard.py |
Comprehensive 11-step setup wizard with conflict resolution |
enhanced_auto_sync.py |
Offline/online sync orchestration |
offline_sync_manager.py |
Offline state management and session tracking |
Stage1_conflict_resolution.py |
High-level conflict strategy selection |
stage2_conflict_resolution.py |
File-by-file conflict resolution |
conflict_resolution_integration.py |
Conflict resolution integration layer |
backup_manager.py |
File-based backup system with auto-cleanup |
ui_elements.py |
Professional UI components library |
wizard_steps.py |
Setup step functions (extracted via dependency injection) |
github_setup.py |
Git/GitHub functions (extracted via dependency injection) |
- Complex git operations simplified for users
- Intelligent handling of merge conflicts, rebases, and force pushes
- Automatic upstream tracking configuration
- Smart detection of unpushed commits and offline changes
- Comprehensive edge case detection and handling
- Graceful recovery from network interruptions
- Automatic fallback mechanisms for failed operations
- Detailed logging for troubleshooting
- Native support for Windows and Linux
- Handles various Obsidian installation methods (native, Snap, Flatpak, AppImage)
- Platform-optimized file operations and process management
git clone https://github.com/AbijithBalaji/ogresync.git
cd ogresync
pip install -r requirements.txt
python Ogresync.pyFor full source code, tests, and development documentation:
git clone -b Development https://github.com/AbijithBalaji/ogresync.gitNote: You are currently viewing the Development branch which includes:
- Complete test suite (30+ test files)
- Development documentation (DEVELOPMENT.md)
- Advanced debugging and build tools
| Component | Requirement |
|---|---|
| OS | Windows 10+, Linux (kernel 3.2+) |
| Memory | 512 MB RAM minimum |
| Storage | 100 MB free space |
| Dependencies | Git, Obsidian |
- Local-first approach: Your notes remain on your device
- Encrypted transit: All GitHub communication uses HTTPS/SSH
- No telemetry: No usage data is collected or transmitted
- Open source: Complete transparency and auditability
- Private repositories: Keep your data secure with private GitHub repos
We welcome contributions from the community! If you'd like to contribute to Ogresync, please check our Contributing Guide for detailed information on:
- Development setup
- Code standards
- Pull request process
- Issue reporting guidelines
- Documentation: Wiki
- Bug Reports: Issues
- Feature Requests: Discussions
- Contact: abijith.balaji@gmail.com
This project was born out of necessity and passion for both Obsidian and open-source solutions. As a developer who couldn't afford the $9 monthly subscription for Obsidian Sync, I started by creating a simple git-based synchronization script for my personal use case.
What began as a mini-scale solution for syncing my notes between devices quickly evolved into something much larger. As I encountered various edge cases, network interruptions, and collaboration scenarios, I found myself building increasingly sophisticated git logic to handle these challenges.
Today, Ogresync represents months of development, testing, and refinement. It handles complex git operations, provides intelligent conflict resolution, supports offline workflows, and offers the kind of reliability you'd expect from commercial software - all while remaining free and open source.
The goal was simple: make Obsidian synchronization accessible to everyone, regardless of their budget or technical expertise, while providing even more advanced features than traditional sync solutions.
Ogrelix is an MSME-registered startup based in India, focused on building innovative, simple, and impactful digital tools. While we're not a formal private limited company, our team is passionate about solving real-world problems through open-source and community-driven development.
Licensed under the GPL License - free for personal and commercial use.