magneto

Obsidian GitHub Sync Plugin

Sync your Obsidian vault to a GitHub repository. Works on both mobile and desktop without requiring Git to be installed locally.

Features

• 🔄 Full Sync: Push local changes and pull remote changes
• ⬆️ Push to GitHub: Upload all local vault files to your repository
• ⬇️ Pull from GitHub: Download all files from your repository
• ⏰ Auto Sync: Optionally sync at regular intervals (5-120 minutes)
• 📱 Mobile Compatible: Uses GitHub REST API, no Git installation needed
• 🔒 Private Repos: Works with private repositories (auto-create is possible when your token allows it)
• 📁 Exclusions: Configure folders and files to exclude from sync
• 🖼️ Binary Files: Supports images, PDFs, and other binary files

Installation

From Community Plugins (Recommended)

1. Open Settings → Community plugins
2. Disable Restricted mode
3. Click Browse and search for "MAGNETO"
4. Click Install, then Enable

Manual Installation

1. Download main.js, manifest.json, and styles.css from the latest release
2. Create folder: <YourVault>/.obsidian/plugins/magneto/
3. Copy the downloaded files into the folder
4. Reload Obsidian and enable the plugin

Note: the folder name stays magneto because the plugin id is still magneto.

Setup

MAGNETO works with either:

• Recommended (most secure): a private repo + a fine-grained PAT restricted to that single repo
• Alternative (easiest / auto-create repo): a classic PAT with broad repo scope

Recommended setup (private repo + restricted token)

1) Create a private GitHub repository

You must create the repo first (fine-grained tokens can only be restricted to repos that already exist).

1. Go to https://github.com/new
2. Create a Private repository (example: obsidian-vault)
3. Optional (recommended): check Add a README so GitHub initializes the default branch (usually main)

2) Generate a fine-grained token (restricted to that repo)

1. GitHub → Settings → Developer settings
2. Personal access tokens → Fine-grained tokens
3. Click Generate new token
4. Configure:

• Token name: Obsidian MAGNETO (restricted)
• Expiration: set a reasonable expiry
• Resource owner: the account/org that owns the repo

5. Under Repository access:

• Select Only select repositories
• Choose your repo (example: obsidian-vault)

6. Under Repository permissions, set:

• Contents: Read and write
• Metadata: Read-only

7. Click Generate token and copy it immediately

3) Configure MAGNETO in Obsidian

1. Obsidian → Settings → Community plugins → MAGNETO
2. Set:

• GitHub username: your GitHub username
• Personal access token: paste the fine-grained token
• Repository name: repo name only (example: obsidian-vault, not owner/obsidian-vault)
• Branch: usually main

3. Click Test connection

Alternative setup (classic PAT with repo scope)

Use this if you want MAGNETO to potentially auto-create the repo during Push/Sync, or if fine-grained tokens aren’t an option.

1. Go to https://github.com/settings/tokens
2. Tokens (classic) → Generate new token (classic)
3. Select scope: repo
4. Copy the token immediately

Then configure MAGNETO the same way in Obsidian settings.

Start syncing

• Use the ribbon icon (git-branch icon) for quick sync
• Or use the Command Palette (Ctrl/Cmd + P):
  • MAGNETO: Push to GitHub
  • MAGNETO: Pull from GitHub
  • MAGNETO: Sync with GitHub
• Or use the buttons in the settings tab

Settings

Default Exclusions

By default, these folders are excluded:

• .obsidian/plugins - Plugin files (too large, use plugin manager)
• .obsidian/themes - Theme files
• .trash - Deleted files

How It Works

This plugin uses the GitHub REST API to sync files. Unlike traditional Git sync plugins that require Git to be installed, MAGNETO:

1. Reads all files in your vault
2. Uploads them to GitHub using the Git Data API (efficient batch uploads)
3. Downloads any remote-only files to your vault

This makes it perfect for Obsidian Mobile where Git isn't available.

Commands

Troubleshooting

"Connection failed"

• Verify your GitHub username is correct
• Ensure your token has the right permissions:
  • Fine-grained PAT: Contents RW + Metadata RO (and restricted to the correct repo)
  • Classic PAT: repo scope
• Check that the token hasn't expired

Files not syncing

• Check the Excluded Folders and Excluded Files settings
• Make sure the file isn't in .obsidian/plugins (excluded by default)

Large vaults

• The plugin uses batch uploads for efficiency
• Very large vaults (10,000+ files) may take a few minutes for the first sync

Development

# Install dependencies
npm install

# Build for development (watch mode)
npm run dev

# Build for production
npm run build

# Run linter
npm run lint

See CONTRIBUTING.md for detailed development guidelines.

Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Documentation

Author

Vishal Sharma

• GitHub: @vishal-go
• Email: [email protected]

License

MIT License - see LICENSE for details.