Git Sync Setup

Syncing Notes with Git

Strayfiles can automatically commit your changes to Git. This works great for notes that live in Git repositories.

Looking for GitHub Sync? This page covers the free Git auto-commit feature for notes in existing repos. For the Pro add-on that backs up all your notes to a dedicated GitHub repository with dual-sync support, see GitHub Sync (Pro).

Basic Setup

Enable auto-commit in your strayfiles.toml:

[sync]
git_auto_commit = true
commit_message = "strayfiles: auto-save"
git_remote = "origin"

How It Works

You edit a note in Strayfiles
You save (or auto-save triggers)
Strayfiles commits the change
Commit pushed to your remote

Configuration Options

Setting	Default	Description
`git_auto_commit`	`false`	Enable automatic commits
`commit_message`	`"strayfiles: auto-save"`	Commit message template
`git_remote`	`"origin"`	Remote to push to

Commit Messages

The default message is "strayfiles: auto-save". Customize it:

[sync]
commit_message = "docs: update via strayfiles"

Or use conventional commits:

[sync]
commit_message = "chore(notes): auto-save"

When to Use Git Sync

Good for:

Notes in code repositories
Documentation alongside code
CLAUDE.md and similar context files
Anything already version-controlled

Not ideal for:

Personal notes (use folder sync or Pro instead)
Rapid editing (many small commits)
Large binary attachments

Notes in Repos vs. Standalone

Notes in code repos:

my-project/
├── src/
├── CLAUDE.md        ← Git synced with project
├── docs/
│   └── setup.md     ← Git synced with project
└── .git/

Standalone notes repo:

~/notes/
├── ideas/
├── work/
├── personal/
├── strayfiles.toml
└── .git/            ← Dedicated notes repo

Both work with Git sync.

Setting Up a Notes Repo

Create a dedicated Git repo for notes:

mkdir ~/notes
cd ~/notes
git init
git remote add origin git@github.com:you/notes.git

Add Strayfiles config:

# ~/notes/strayfiles.toml
version = 1

[settings]
roots = ["./"]
exclude = [".git/**"]

[sync]
git_auto_commit = true

Working with Branches

Git sync commits to your current branch. If you use feature branches:

Strayfiles commits to current branch
Switch branches in terminal as needed
Commits follow normal Git workflow

Conflicts with Git Sync

If you edit on multiple devices before pushing:

Git handles the merge on pull
Resolve conflicts using Git tools
Strayfiles re-indexes after resolution

For complex merge needs, use Git directly rather than Strayfiles’ conflict resolution.

Disabling for Specific Notes

Git sync applies to all notes in Git repos. To exclude specific files:

Add to .gitignore (stops Git tracking entirely)
Or use sync: false in frontmatter (keeps file local-only for Stray Cloud and GitHub Sync Pro)

---
strayfiles:
  enabled: true
  sync: false
---

The sync: false option keeps your note tracked by Strayfiles but prevents it from syncing to cloud backends.

Manual Git Workflow

Prefer manual control? Disable auto-commit:

[sync]
git_auto_commit = false

Then commit and push manually when ready.

Tips

Review before push: Disable auto-commit, review changes with git diff, then commit manually.

Squash auto-commits: If you accumulate many small commits, squash them before pushing.

Use meaningful messages: For important changes, commit manually with descriptive messages instead of relying on auto-commit.

Multiple remotes: Git sync pushes to one remote. To push to multiple, use Git hooks or manual pushing.

Troubleshooting

“Not a git repository”: The note isn’t in a Git repo. Initialize one or move the note.

“Remote not found”: Configure the remote: git remote add origin <url>

“Push rejected”: Pull first to get remote changes: git pull

“Uncommitted changes”: Strayfiles only commits its own changes. Commit or stash other changes first.

Git Sync vs GitHub Sync (Pro)

Feature	Git Sync (Free)	GitHub Sync (Pro)
Cost	Free	Pro subscription
Use case	Notes in existing repos	Dedicated notes backup
Authentication	Your Git credentials	Secure Device Flow OAuth
Dual-sync	No	Yes, with Stray Cloud
Conflict resolution	Use Git tools	Built-in 3-way merge
iOS visibility	No	Yes (read-only status)
tree.json manifest	No	Yes

Choose Git Sync when your notes live in code repositories and you want them committed alongside your code.

Choose GitHub Sync (Pro) when you want a dedicated notes repository with full Strayfiles integration and dual-sync support.