DiscoverTrendingDashboardsPluginsGuidePublish
NOTEXheldon

Git Folder Sync

Synchronize files in your Obsidian Vault with a specified directory in the designated GitHub repository (rather than the entire repository).

6 StarsGitHub

Git Folder Sync Obsidian Plugin

An Obsidian plugin that supports synchronization with GitHub repositories, built with a modern interface and hot reload development support.

Features

  • šŸ”„ Bidirectional Sync: Support syncing notes to GitHub or pulling notes from GitHub
  • šŸŽÆ Single File Operations: Sync individual files currently being edited
  • šŸ“ Batch Operations: Support batch synchronization of entire Vault
  • šŸ”§ Visual Configuration: Modern configuration interface with intuitive controls
  • šŸš€ Hot Reload Development: Support for hot reload during development
  • šŸ“‚ Recursive Folders: Complete support for recursive synchronization of folder structures
  • šŸŒ Internationalization: Support for Chinese and English languages
  • šŸ’¾ Smart Caching: File status caching to reduce GitHub API calls
  • šŸ“Š Real-time Status: Status bar showing file sync status and last modified time
  • šŸ–¼ļø Image Processing: Automatic image upload to cloud storage when pasting images

Installation

Manual Installation

  1. Download the latest release files
  2. Extract files to your Obsidian plugins directory: {vault}/.obsidian/plugins/git-folder-sync/
  3. Restart Obsidian
  4. Enable the "Git Folder Sync" plugin in settings

Development Installation

  1. Clone this repository to your plugins directory:

    cd {vault}/.obsidian/plugins/
git clone https://github.com/Xheldon/git-folder-sync git-folder-sync
cd git-folder-sync

  2. Install dependencies:

    npm install

  3. Development mode (with hot reload):

    npm run dev

  4. Build production version:

    npm run build

Configuration

1. GitHub Personal Access Token

First, create a GitHub Personal Access Token:

  1. Visit GitHub Settings > Developer settings > Personal access tokens
  2. Click "Generate new token (classic)"
  3. Select the following permissions:
    • repo (Full repository access)
  4. Copy the generated token

2. Repository Path Configuration

Repository path formats:

  • https://github.com/username/repo/path/to/folder (Standard GitHub URL)
  • username/repo/path/to/folder (Short format)

Examples:

  • https://github.com/yourusername/your-repo/docs/notes
  • username/notes/obsidian-vault

3. Image Processing Configuration (Optional)

The plugin includes an optional image processing feature that automatically uploads pasted images to cloud storage services.

Supported Cloud Storage Providers

  • Aliyun OSS: Alibaba Cloud Object Storage Service
  • Tencent COS: Tencent Cloud Object Storage
  • AWS S3: Amazon Simple Storage Service
  • Cloudflare R2: Cloudflare's S3-compatible storage

Configuration Steps

  1. Enable Image Processing: Turn on the "Enable Image Processing" toggle in settings
  2. Select Cloud Provider: Choose your preferred cloud storage service
  3. Configure Credentials: Enter your cloud storage credentials:
    • Access Key ID / Secret ID
    • Access Key Secret / Secret Key
    • Bucket Name
    • Region (required for all providers)
    • Endpoint (required for Cloudflare R2 only)
    • CDN URL (optional, for faster image loading)

Image Upload Settings

  • Keep Images Locally: Optionally keep a local copy of uploaded images
  • Local Image Path: Specify where to store local image copies (when enabled)
  • Upload Path Template: Customize the remote storage path using variables:
    • {YYYY}: Current year
    • {MM}: Current month
    • {DD}: Current day
    • {FILENAME}: Current file name
    • {FOLDER}: Current folder name

How It Works

  1. Paste Image: When you paste an image in a markdown file
  2. Automatic Upload: The image is automatically uploaded to your configured cloud storage
  3. Link Replacement: The pasted image is replaced with a CDN link
  4. Local Copy (optional): A local copy is saved if enabled

Behavior Options

  • Image Processing Disabled: Uses Obsidian's default image handling
  • Image Processing Enabled + Cloud Storage Configured: Uploads to cloud and inserts CDN links
  • Image Processing Enabled + Local Storage Only: Saves images to specified local directory
  • Image Processing Enabled + No Configuration: Shows configuration reminder

Usage

Settings Interface

Click the settings icon in the left sidebar to open the configuration interface, or access it through Obsidian's plugin settings.

Note Sync Menu

While editing notes, you can access the sync menu through:

  1. Command palette: Ctrl/Cmd + P ā†’ Search for "Show Sync Menu"
  2. Right-click in editor ā†’ Select "Git Folder Sync"
  3. Status bar sync button (bottom right)

Menu options:

  • Sync current file to remote: Upload current file to GitHub
  • Pull remote to current file: Download file from GitHub to overwrite local

Configuration Interface Features

Basic Settings

  • Interface Language: Choose between Chinese, English, or follow Obsidian
  • GitHub Personal Token: Enter your access token
  • GitHub Repository Path: Configure target repository and path
  • Show Ribbon Icon: Toggle sidebar button visibility

Image Processing Settings

  • Enable Image Processing: Master toggle for image upload functionality
  • Cloud Storage Provider: Select from Aliyun OSS, Tencent COS, AWS S3, or Cloudflare R2
  • Storage Credentials: Configure access keys, bucket, region, and optional CDN URL
  • Local Image Storage: Option to keep local copies of uploaded images
  • Upload Path Template: Customize remote storage path with date and file variables

Batch Operations (Danger Zone)

  • Initialize Repository: Download all files from remote when Vault is empty
  • Force Sync Remote to Local: Sync remote files to local (overwrites same-name files)
  • Force Sync Local to Remote: Sync local files to remote
  • Clear File Cache: Clear all cached file status data

Sponsor

  • Support Development: Links to sponsor the project development

Development

Project Structure

ā”œā”€ā”€ main.ts              # Main plugin file
ā”œā”€ā”€ types.ts             # Type definitions
ā”œā”€ā”€ github-service.ts    # GitHub API service
ā”œā”€ā”€ cos-service.ts       # Cloud storage service
ā”œā”€ā”€ file-cache.ts        # File caching service
ā”œā”€ā”€ i18n-simple.ts       # Internationalization system
ā”œā”€ā”€ styles.css          # Stylesheet
ā”œā”€ā”€ manifest.json       # Plugin manifest
ā”œā”€ā”€ package.json        # Project configuration
ā”œā”€ā”€ tsconfig.json       # TypeScript configuration
ā”œā”€ā”€ esbuild.config.mjs  # Build configuration
ā””ā”€ā”€ version-bump.mjs    # Version management script

Development Commands

# Install dependencies
npm install

# Development mode (hot reload)
npm run dev

# Build production version
npm run build

# Version management
npm run version

Tech Stack

  • TypeScript: Primary development language
  • Obsidian API: Core plugin API
  • GitHub API: Repository operations via @octokit/rest
  • esbuild: Fast build tool
  • i18n: Custom internationalization system

Important Notes

  1. Permission Requirements: Requires write access to GitHub repository
  2. File Conflicts: Force sync will overwrite existing files, use with caution
  3. Network Requirements: Requires stable network connection to access GitHub API
  4. Token Security: Keep your GitHub Personal Access Token secure
  5. Rate Limits: GitHub API has rate limits (5000 requests/hour for authenticated users)

Contributing

Issues and Pull Requests are welcome!

Sponsor

If this plugin helps you, consider buying me a coffee ā˜•

PayPal

For users in mainland China: https://www.xheldon.com/donate/

Your support motivates me to continue developing and maintaining this project!

License

MIT License

How to Install

  1. Download the template file from GitHub
  2. Move it anywhere in your vault
  3. Open it in Obsidian ā€” done!
Get Template

Stats

Stars

6

Forks

0

License

MIT

Last updated 5mo ago