Skip to main content
Scratch includes built-in Git integration for syncing notes across multiple devices. Your notes folder becomes a Git repository, and you can push/pull to any Git remote (GitHub, GitLab, Bitbucket, self-hosted, etc.).

​
Why Git for Sync?

  • Full version history - Every change is tracked with commit messages
  • Works with any Git remote - Not locked into a proprietary service
  • Merge conflict handling - Git’s robust merge capabilities
  • Works offline - Commit locally, push when connected
  • Compatible with other tools - Obsidian Git plugin, Working Copy, etc.
Git sync is optional. If you only use Scratch on one device or prefer cloud storage (Dropbox, iCloud), you don’t need Git.

​
Prerequisites

Before enabling Git sync:
  1. Install Git - Download from git-scm.com
  2. Create a remote repository - GitHub, GitLab, or any Git host
  3. Set up SSH keys (recommended) or HTTPS auth for push/pull
For GitHub, create a private repository to keep your notes secure. Public repos expose your notes to the internet.

​
Initial Setup

​
Step 1: Initialize Git Repository

1

Open Git Settings

Open Settings → General → Git Integration in Scratch.
2

Initialize Repository

Click Initialize Git Repository. This runs git init in your notes folder.
3

Verify Status

The Git status indicator appears in the sidebar showing uncommitted changes.

​
Step 2: Add Remote Repository

Connect your local repository to a remote:
1

Copy Remote URL

Get the repository URL from your Git host:
2

Add Remote in Scratch

In the Git status panel (bottom of sidebar), click Add Remote and paste the URL.
3

Verify Connection

The remote URL appears in the Git status panel.
SSH vs HTTPS: SSH is recommended for seamless push/pull without password prompts. Set up SSH keys on your Git host first.

​
Step 3: First Commit and Push

Commit your existing notes and push to the remote:
1

Review Changes

The Git status shows how many files have changed. For a fresh repo, all notes will be “new.”
2

Write Commit Message

In the commit input at the bottom of the sidebar, write a message:
Initial commit: Add all notes
3

Commit

Click Commit or press Enter. Scratch runs git add -A and git commit -m.
4

Push to Remote

Click Push (↑ icon) to push commits to the remote. First push sets upstream tracking automatically.

​
Daily Workflow

Once set up, syncing is straightforward:

​
On Device A (Making Changes)

  1. Edit notes as usual - Scratch auto-saves every 500ms
  2. Commit changes - Write a commit message and click Commit
  3. Push - Click the Push button (↑) to upload to remote

​
On Device B (Pulling Changes)

  1. Pull latest changes - Click the Pull button (↓) in Git status
  2. Notes auto-reload - Scratch detects file changes and reloads the current note
Pull before editing: Always pull when switching devices to avoid merge conflicts. Scratch shows ahead/behind counts to remind you.

​
Git Status Indicators

The Git panel (bottom of sidebar) shows real-time status:
IndicatorMeaning
2 changes2 uncommitted files (staged or unstaged)
↑ 33 commits ahead of remote (need to push)
↓ 11 commit behind remote (need to pull)
origin/mainCurrent branch and remote
Git status auto-refreshes when files change (1 second debounce). You don’t need to manually refresh.

​
Handling Conflicts

If you edited the same note on two devices without syncing:
  1. Pull fails with conflict - Scratch shows an error: “Pull failed due to merge conflicts”
  2. Resolve manually - Open the notes folder in a terminal or GUI Git client
  3. Run merge - Use git pull and resolve conflicts in a text editor
  4. Commit the merge - git add . and git commit
  5. Return to Scratch - Click Refresh to reload notes
Scratch doesn’t have a built-in merge conflict resolver. For complex conflicts, use Git CLI or a GUI tool like GitKraken, Tower, or GitHub Desktop.

​
Advanced: Command Line Workflow

You can mix Scratch with command-line Git for advanced operations: 
cd ~/Documents/Notes  # Your notes folder

# View commit history
git log --oneline

# Create a branch for experiments
git checkout -b experiments

# Merge a branch
git checkout main
git merge experiments

# Push to a different remote
git remote add backup [email protected]:user/notes.git
git push backup main
Scratch watches for file changes and automatically reloads notes when you commit externally.

​
Sync with Multiple Devices

​
Adding a Second Device

1

Install Scratch

Download and install Scratch on the new device.
2

Clone Repository

Clone your notes repo from the terminal:
git clone [email protected]:username/notes.git ~/Documents/Notes
3

Set Notes Folder

In Scratch, open Settings → General and select the cloned folder.
4

Verify Git Status

Scratch detects the existing .git folder and shows Git status automatically.
You don’t need to “Initialize Repository” on the second device. Scratch auto-detects existing Git repos.

​
Troubleshooting

​
”Authentication failed” Error

SSH: Ensure your SSH key is added to the Git host (GitHub → Settings → SSH Keys). HTTPS: Git may prompt for username/password in the background. Use SSH or a credential helper: 
git config --global credential.helper cache

​
“Repository not found”

Check the remote URL: 
cd ~/Documents/Notes
git remote -v
Update if incorrect: 
git remote set-url origin [email protected]:username/notes.git

​
“Could not connect to remote”

Check your internet connection and firewall settings. Test with: 
ssh -T [email protected]  # For SSH
curl https://github.com  # For HTTPS

​
Notes Not Reloading After Pull

Scratch uses a file watcher to detect changes. If notes don’t reload:
  1. Press Cmd+R to manually reload the current note
  2. Toggle to another note and back
  3. Restart Scratch if the issue persists

​
Git Settings Storage

Git configuration is stored in two places:
  1. .git/ folder - Standard Git metadata (commits, branches, remotes)
  2. .scratch/settings.json - Scratch-specific settings (gitEnabled flag)
Both are in your notes folder and sync across devices when you clone the repo.
Add .scratch/ to .gitignore if you want device-specific settings (theme, pinned notes). Otherwise, settings sync too.

​
Best Practices

  1. Commit frequently - Small commits with clear messages are easier to track
  2. Pull before editing - Especially when switching devices
  3. Use descriptive commit messages - Future you will thank you
  4. Don’t commit large binaries - Images in assets/ are fine, but avoid videos or large PDFs
  5. Set up .gitignore - Exclude OS files (.DS_Store, Thumbs.db)

​
Example .gitignore

Create .gitignore in your notes folder: 
# OS files
.DS_Store
Thumbs.db

# Editor files
.vscode/
*.swp

# Scratch cache (optional - exclude for device-specific settings)
# .scratch/

​
Limitations

  • No auto-commit - Scratch doesn’t auto-commit on every save (by design)
  • No conflict resolution UI - Use Git CLI or GUI tools for merge conflicts
  • No branch switching - Scratch works with your current branch; switch branches externally
  • No Git LFS - Large files (>100MB) may cause push failures; use Git LFS if needed
Scratch’s Git integration is intentionally simple. For advanced workflows (rebasing, cherry-picking, submodules), use Git CLI alongside Scratch.

Build docs developers (and LLMs) love

Get started for freeTalk to us