Skip to content

feat: persist additional repo configs in vault file for cross-device sync #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rhoades-brown merged 2 commits into from
May 30, 2026
Merged

feat: persist additional repo configs in vault file for cross-device sync #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d256dca
feat: persist additional repo configs in vault file for cross-device …
rhoades-brown May 30, 2026
8f0f06a
Merge branch 'main' into feat/vault-repo-config
rhoades-brown May 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
262 changes: 143 additions & 119 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,187 +1,211 @@
# GitHub Octokit - Obsidian Plugin
# GitHub Octokit Sync

[![CI](https://github.com/rhoades-brown/obsidian-github/actions/workflows/ci.yml/badge.svg)](https://github.com/rhoades-brown/obsidian-github/actions/workflows/ci.yml)

Sync your Obsidian Vault with a GitHub repository using the official GitHub API (Octokit).

This plugin provides a simple and efficient way to sync your Obsidian vault with a GitHub repository without external dependencies like Git CLI. Use GitHub as a remote backup and collaboration tool for your Obsidian vault on any device.
Sync your Obsidian vault with GitHub using the official Octokit API — no Git CLI required. Use GitHub as a remote backup and collaboration tool for your vault on any device, including mobile.

## Features

- **Two-way sync**: Pull changes from GitHub and push local changes
- **Conflict detection**: Automatically detects when files have been modified both locally and remotely
- **Visual diff view**: Side-by-side and inline diff comparison for conflicting files
- **Batch commits**: Efficiently commits multiple files in a single operation
- **Auto-sync options**: Sync on save, on interval, or on startup
- **Subfolder mapping**: Sync your vault to a specific subfolder in the repository
- **Ignore patterns**: Configure which files and folders to exclude from sync
- **Commit history**: View recent commits directly in Obsidian
- **Sync logging**: Debug sync operations with configurable logging
- **File status indicators**: See at a glance which files are added, modified, or deleted
### Sync

- **Two-way sync** — pull changes from GitHub and push local changes in a single operation
- **Selective sync** — stage individual files or sync everything at once
- **Auto-sync** — sync on save, on a configurable interval, or on startup
- **Subfolder mapping** — sync your vault to a specific subfolder within the repository
- **Configuration sync** — optionally sync `.obsidian` settings (themes, snippets, hotkeys) across devices
- **Batch commits** — multiple file changes are committed in a single Git tree operation for efficiency

### Multi-repo support

- **Additional repositories** — sync extra GitHub repos into specific vault directories (e.g., a shared notes folder)
- **Independent sync** — each additional repo syncs independently with its own branch, subfolder, and ignore patterns
- **Shared config across devices** — additional repo configurations are stored in `.github-sync-repos.json` inside the vault, so they are synced with the primary repo and automatically picked up on other devices
- **Per-repo tokens** — use the main token or a separate PAT for each additional repo

### Security

- **Encrypted token storage** — all GitHub tokens (main and per-repo) are stored in Obsidian's encrypted `SecretStorage`, never in plaintext `data.json`
- **Auto-migration** — existing plaintext tokens are automatically migrated to `SecretStorage` on first load after upgrade

### Conflict resolution

- **Automatic detection** — files modified both locally and on GitHub are flagged as conflicts
- **Visual diff view** — side-by-side and inline diff comparison for conflicting files
- **Resolution options** — keep local, keep remote, or edit manually and re-sync

### Sync panel

- **File change overview** — files grouped by status (added, modified, deleted, conflict) with repo labels for multi-repo setups
- **Commit history** — view recent commits with author, message, and timestamp (collapsible)
- **Live logs** — real-time sync log viewer with filtering (collapsible)
- **Persistent UI state** — panel collapse states are remembered across restarts via per-vault local storage

### Other

- **Clipboard access** — the "Copy logs" and "Export logs" buttons write sync log text to the system clipboard (write-only; the plugin never reads from the clipboard)
- **Ignore patterns** — glob-based patterns to exclude files and folders from sync
- **Commit message templates** — customisable templates with `{date}` and `{action}` variables
- **Status bar** — live sync status indicator; click to open the sync panel
- **Ribbon icon** — left-click to sync, right-click for quick actions (pull, push, open panel, settings)
- **Configurable logging** — adjustable log level (debug/info/warn/error) with optional file persistence
- **Mobile compatible** — works on iOS and Android (not desktop-only)

## Prerequisites

- Obsidian
- A GitHub account
- Obsidian v1.12.7 or later
- A GitHub account with a Personal Access Token

## Installation

> **Note**: Please make a backup copy of your vault before installing this plugin. This plugin is still in early development and there may be bugs.
> **Note**: Back up your vault before installing. This plugin is in early development.

### From Obsidian Community Plugins (Coming Soon)
### From Obsidian Community Plugins

1. Open Settings → Community Plugins
2. Search for "GitHub Octokit"
3. Click Install, then Enable
1. Open **Settings → Community plugins → Browse**
2. Search for "GitHub Octokit Sync"
3. Select **Install**, then **Enable**

### BETA (BRAT) Installation
### BRAT (for beta releases, not recommended)

1. Install [BRAT](https://github.com/TfTHacker/obsidian42-brat)
2. Open Settings → Community Plugins → BRAT
3. Click "Add beta plugin"
4. Enter this repository `rhoades-brown\obsidian-github`.
5. Choose 'latest' as the version.
6. Click "Add Plugin"
2. Open **Settings → Community plugins → BRAT**
3. Select **Add beta plugin**
4. Enter `rhoades-brown/obsidian-github`
5. Choose **latest** as the version
6. Select **Add Plugin**

### Manual Installation
### Manual

1. Download `main.js`, `manifest.json`, and `styles.css` from the latest release
2. Create a folder `<vault>/.obsidian/plugins/github-octokit/`
1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/rhoades-brown/obsidian-github/releases)
2. Create `<vault>/.obsidian/plugins/github-octokit/`
3. Copy the downloaded files into this folder
4. Reload Obsidian and enable the plugin in Settings → Community Plugins
4. Reload Obsidian and enable the plugin in **Settings → Community plugins**

## Setup

### 1. Generate a GitHub Personal Access Token (PAT)

1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens)
2. Click "Generate new token (classic)"
3. Give it a descriptive name (e.g., "Obsidian Vault Sync")
4. Select scopes:
- `repo` (Full control of private repositories)
5. Click "Generate token" and copy it
### 1. Generate a GitHub Personal Access Token

### 2. Configure the Plugin
1. Go to [GitHub → Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens)
2. Select **Generate new token (classic)**
3. Name it (e.g., "Obsidian Vault Sync") and select the `repo` scope
4. Select **Generate token** and copy it

1. Open Obsidian Settings → GitHub Octokit
2. Paste your Personal Access Token
3. Click "Connect" to authenticate
4. Select a repository from the dropdown
5. Optionally configure:
- Branch name (default: main)
- Vault subfolder to sync
- Sync triggers (on save, interval, startup)
- Commit message template
### 2. Configure the plugin

## Usage

### Manual Sync
1. Open **Settings → GitHub Octokit Sync**
2. Paste your token and select **Connect**
3. Select a repository from the dropdown
4. Optionally configure branch, subfolder, sync triggers, and commit message template

- **Command Palette**: Press `Ctrl/Cmd + P` and search for:
- "GitHub Octokit: Sync now" - Full bidirectional sync
- "GitHub Octokit: Pull from GitHub" - Download remote changes
- "GitHub Octokit: Push to GitHub" - Upload local changes
### 3. Add additional repositories (optional)

- **Ribbon Icon**: Click the GitHub icon in the left ribbon, or right-click for quick actions
1. In settings, scroll to **Additional repositories**
2. Select **Add** and enter the repo owner, name, branch, and local vault directory
3. Choose whether to use the main token or a separate one
4. The configuration is saved to `.github-sync-repos.json` in your vault and synced automatically

- **Status Bar**: Click the sync status in the bottom-right to open the sync panel

### Sync Panel
## Usage

Open the sync panel via:
### Commands

- Command: "GitHub Octokit: Open sync panel"
- Right-click the ribbon icon → "Open Sync Panel"
- Click the status bar indicator
Open the command palette (`Ctrl/Cmd + P`) and search for:

The sync panel shows:
| Command | Description |
| ------- | ----------- |
| **Sync now** | Full bidirectional sync |
| **Pull from GitHub** | Download remote changes only |
| **Push to GitHub** | Upload local changes only |
| **Open sync panel** | Open the sidebar sync panel |
| **Open sync modal** | Open the sync modal |
| **Open diff view** | Open the diff comparison view |
| **View sync conflicts** | Jump to conflicts in the sync panel |
| **Open GitHub settings** | Open plugin settings |

- Files with changes (grouped by status)
- Conflict resolution options
- Recent commit history
### Ribbon and status bar

### Resolving Conflicts
- **Left-click** the GitHub ribbon icon to sync
- **Right-click** for quick actions (pull, push, open panel, settings)
- **Click the status bar** indicator to open the sync panel

When a file has been modified both locally and on GitHub:
### Resolving conflicts

1. The file appears in the "Conflicts" section
2. Click "Diff" to see a side-by-side comparison
1. Conflicting files appear in the sync panel under **Conflicts**
2. Select **Diff** to see a side-by-side comparison
3. Choose a resolution:
- **Keep Local**: Use your local version
- **Keep Remote**: Use the GitHub version
- **Manual**: Edit the file yourself, then sync again
- **Keep local** — use your version
- **Keep remote** — use the GitHub version
- **Manual** — edit the file yourself, then sync again

## Configuration Options
## Configuration

| Setting | Description |
|---------|-------------|
| **GitHub Token** | Your Personal Access Token |
| ------- | ----------- |
| **GitHub token** | Your Personal Access Token (stored encrypted) |
| **Repository** | The GitHub repo to sync with |
| **Branch** | Branch name (default: main) |
| **Vault Subfolder** | Only sync files in this folder |
| **Sync on Save** | Auto-sync when you save a file |
| **Sync on Interval** | Sync automatically every X minutes |
| **Sync on Startup** | Sync when Obsidian opens |
| **Commit Message** | Template for commit messages. Variables: `{date}`, `{action}` |
| **Conflict Strategy** | Default resolution: ask, keep-local, keep-remote, keep-both |
| **Status Bar** | Show/hide sync status in status bar |
| **Notifications** | Show/hide sync notifications |
| **Enable Logging** | Log sync operations for debugging |
| **Log Level** | Minimum log level: debug, info, warn, error |
| **Persist Logs** | Save logs to a file in your vault |

## Ignore Patterns

By default, the following are excluded from sync:

- `.obsidian/workspace.json`
- `.obsidian/workspace-mobile.json`
- `.obsidian/github-sync-metadata.json`
- `.git/**`
- `.gitignore`

Add custom patterns in Settings → GitHub Octokit → Ignore Patterns:

- `*.log` - All log files
- `private/**` - Everything in the private folder
- `*.tmp` - All .tmp files
- `.obsidian/**` - All Obsidian settings (if desired)
| **Subfolder path** | Sync only a subfolder of the remote repo |
| **Sync configuration** | Include `.obsidian` settings in sync |
| **Sync on save** | Auto-sync when you modify a file (debounced) |
| **Sync on interval** | Sync every N minutes |
| **Sync on startup** | Sync when Obsidian opens |
| **Commit message** | Template with `{date}` and `{action}` variables |
| **Conflict strategy** | Default resolution: manual, keep-local, keep-remote, keep-both |
| **Status bar** | Show/hide the sync status indicator |
| **Notifications** | Show/hide sync result notices |
| **Logging** | Enable/disable, set level, optionally persist to file |

## Ignore patterns

The following paths are always excluded from sync:

- `.obsidian/plugins/**` — plugin files are managed separately
- `.obsidian/workspace.json` and `workspace-mobile.json` — machine-specific
- `.git/**`, `.gitignore`

Add custom glob patterns in **Settings → Ignore patterns**:

```text
*.log
private/**
*.tmp
drafts/wip-*
```

## Development & contributing

See [DEVELOPMENT.md](DEVELOPMENT.md) for build instructions, project structure, conventional commit guidelines, and the automated versioning workflow.
See [DEVELOPMENT.md](DEVELOPMENT.md) for build instructions, project structure, conventional commit guidelines, and the automated CI/CD versioning workflow.

## Troubleshooting

### "Authentication failed"

- Verify your token has the `repo` scope
- Check if the token has expired
- Try generating a new token
- Generate a new token and re-connect

### "Rate limit exceeded"

- GitHub limits API requests (5000/hour for authenticated users)
- Wait for the reset time shown in the notification
- GitHub allows 5,000 API requests per hour for authenticated users
- The notification shows when the limit resets
- Reduce sync frequency in settings

### "Conflict detected"

- Open the sync panel to view and resolve conflicts
- Use the diff view to compare versions
- Use the diff view to compare local and remote versions

### Files keep re-syncing

- Check if sync state is being preserved (enable logging to debug)
- Verify line endings are consistent (plugin normalizes to LF)
- Ensure ignore patterns are correctly configured
- Enable debug logging to inspect sync state
- Verify line endings are consistent (the plugin normalises to LF)
- Check that ignore patterns are correctly configured

### Debug with Logs
### Debug with logs

1. Enable logging in Settings → GitHub Octokit → Logging
2. Set log level to "Debug" for verbose output
3. Open the debug console (macOS → cmd+option+i; Windows → ctrl+shift+i) to see real-time logs
4. Or click "View Logs" in settings to see recent entries
1. Enable logging in **Settings → Logging**
2. Set log level to **Debug** for verbose output
3. Open the developer console (`Cmd+Option+I` on macOS, `Ctrl+Shift+I` on Windows) for real-time logs
4. Or select **View logs** in settings to see recent entries in-app

## License

Expand Down
Loading
Loading