Skip to main content
Scratch includes optional git integration for version control and multi-device synchronization. Your notes remain local-first, but you can optionally enable git to track changes and sync across devices.

​
Prerequisites

Git must be installed on your system. Scratch will automatically detect if git is available.
If git is not installed, download it from git-scm.com/downloads

​
Enabling Git

Git integration is completely optional and can be enabled from Settings.
  1. Open Settings (Cmd+, or Ctrl+,)
  2. Go to the General tab
  3. Under Version Control, click Initialize Git Repository
This runs git init in your notes folder and begins tracking changes.

​
Git Operations

Once enabled, Scratch exposes git operations through the sidebar and settings.

​
Commit Changes

The sidebar displays a floating git status indicator showing:
  • Current branch name
  • Number of changed files
  • Number of commits ahead/behind remote
To commit changes:
  1. Click the git status indicator in the sidebar
  2. Enter a commit message
  3. Click Commit
This runs: 
git add -A
git commit -m "your message"

​
Connect a Remote

To enable multi-device sync, connect a remote repository:
  1. Create a repository on GitHub, GitLab, or any git hosting service
  2. Copy the repository URL (HTTPS or SSH)
  3. In Settings → General → Version Control, click Add Remote
  4. Paste the URL and click Connect
This runs: 
git remote add origin <url>
Supported URL formats:
  • HTTPS: https://github.com/username/my-notes.git
  • SSH: [email protected]:username/my-notes.git

​
Push and Pull

Once a remote is connected: First Push: For the initial push, Scratch will set up upstream tracking: 
git push -u origin <branch>
Subsequent Operations: After upstream tracking is configured, use the git status indicator:
  • Push - Sends your commits to the remote
  • Pull - Fetches and merges remote changes
These run: 
git push
git pull --no-rebase

​
Multi-Device Sync

With a remote connected, you can sync notes across multiple devices:
  1. Device A: Make changes, commit, and push
  2. Device B: Pull to receive changes
  3. Repeat as needed
Always commit your changes before pulling to avoid merge conflicts. If you have uncommitted changes, Scratch will warn you.

​
Git Status

The git status indicator shows real-time information:
  • Branch name: Current branch (usually main or master)
  • Changed files: Uncommitted changes in your notes folder
  • Ahead count: Commits waiting to be pushed
  • Behind count: Commits available to pull
  • Remote URL: Connected repository
  • Upstream tracking: Whether the current branch tracks a remote branch

​
Commands Reference

Scratch exposes these git operations through the Rust backend:
OperationGit CommandDescription
Initializegit initCreate a new git repository
Statusgit status --porcelainGet current status
Commitgit add -A && git commit -m "..."Stage and commit all changes
Pushgit pushPush commits to remote
Pullgit pull --no-rebaseFetch and merge remote changes
Fetchgit fetch --quietUpdate remote tracking refs
Add Remotegit remote add origin <url>Connect a remote repository
Push with Upstreamgit push -u origin <branch>Push and set upstream tracking

​
Error Handling

Scratch provides user-friendly error messages for common git issues: Authentication Failed 
Authentication failed. Check your SSH keys or credentials.
For SSH authentication issues, see GitHub’s SSH documentation. Network Issues 
Could not connect to remote. Check your internet connection.
Merge Conflicts 
Pull failed due to merge conflicts. Resolve conflicts manually.
Uncommitted Changes 
Commit your changes before syncing with remote.

​
Implementation Details

Git integration is implemented in src-tauri/src/git.rs using Rust’s std::process::Command to execute git CLI commands. The implementation includes:
  • Git availability detection
  • Repository status tracking
  • Remote configuration management
  • Upstream tracking detection
  • Error parsing and user-friendly messages
  • Timeout configuration for network operations
Scratch uses the git CLI directly rather than a git library (like libgit2) to ensure maximum compatibility and feature parity with standard git workflows.

​
Best Practices

  • Commit frequently: Small, focused commits are easier to manage
  • Write descriptive messages: Explain why changes were made, not just what changed
  • Pull before pushing: Reduces merge conflicts on multi-device setups
  • Use SSH for authentication: More secure than HTTPS with credentials
  • Keep notes folder focused: Avoid mixing notes with other files

​
Disabling Git

Git integration is non-intrusive. If you don’t initialize a repository, Scratch operates in pure local mode with no git overhead. Even with git enabled, all operations are manual - nothing happens automatically. To stop using git, simply remove the .git folder from your notes directory. Scratch will detect this and disable git features.

Build docs developers (and LLMs) love

Get started for freeTalk to us