Brain Dump

Back up your Brain Dump folder with Git

Updated: 2026-08-31

iCloud is good for syncing. But syncing isn't backup.

If you accidentally delete a note, iCloud deletes it everywhere. If you make an edit you regret, iCloud overwrites the old version. If your iCloud account gets compromised, your notes are at risk.

Git gives you real version history. Every change tracked. Every version recoverable. Complete control.

Why back up with Git

Version history See what a note looked like last week, last month, last year. Compare versions. Restore old content.

True backup Push to a private GitHub repo (or GitLab, or your own server) and you have an off-site backup that iCloud can't touch.

Diff viewing See exactly what changed between versions. Useful when you're refining ideas over time.

Branching for experiments Try reorganizing your folder structure in a branch. If it doesn't work, delete the branch. Your main notes stay untouched.

Plain text forever Your notes are already Markdown files. Git is the natural companion for plain text versioning.

How to set it up (Mac)

This takes 5 minutes the first time. After that, it's automatic.

Step 1: Find your Brain Dump folder

Open Terminal and navigate to your Brain Dump folder:

cd ~/Library/Mobile\ Documents/iCloud~com~voicebraindump~app/Documents

(If the path is different, open Finder, go to iCloud Drive → BrainDump folder, right-click, hold Option, and choose "Copy as Pathname")

Step 2: Write a .gitignore first

Do this before your first commit. Brain Dump keeps its working state in a hidden .braindump/ directory inside the vault: per-note sidecars, rendered editor documents, a per-note asset store, recorded audio, a write-ahead transaction log under .braindump/recovery/, and staging temp directories under .braindump/tmp/. Autosave touches those files constantly. Commit them and every git status is thousands of lines of churn with your actual notes buried in it.

cat > .gitignore <<'EOF'
# Brain Dump working state: sidecars, editor documents, assets,
# audio, the recovery transaction log and staging temp dirs.
.braindump/

# Obsidian's local trash
.trash/
.trashes/

# macOS
.DS_Store
EOF

That list is not arbitrary. It is the same set Brain Dump itself skips when it walks a vault, plus .DS_Store.

Keep .obsidian/ in the repository. It holds your real Obsidian configuration: your attachment folder, your template folder, your property type registry. Brain Dump reads those files and writes three of them back by splicing a single key, so versioning them gives you a history of your own vault settings. That is worth having.

If you want your recorded audio backed up, ignore only the churning parts instead:

.braindump/tmp/
.braindump/recovery/

Audio clips live under .braindump/ too. This keeps them, at the cost of a repository that grows with every recording. Audio is binary and Git stores each version whole, so most people should keep the wider ignore above and back audio up separately.

Step 3: Initialize Git

git init
git add .
git commit -m "Initial commit of Brain Dump notes"

That's it. You now have local version history.

Step 4: (Optional) Add a remote backup

If you want off-site backup:

  1. Create a private repository on GitHub (or GitLab, or Bitbucket)
  2. Copy the repository URL
  3. Add it as a remote:
git remote add origin YOUR_REPO_URL_HERE
git push -u origin main

Important: Make sure the repository is private. These are your personal notes. Don't publish them publicly.

How to use it daily

Once set up, backing up is simple:

# Navigate to your Brain Dump folder
cd ~/Library/Mobile\ Documents/iCloud~com~voicebraindump~app/Documents

# See what changed
git status

# Add all changes
git add .

# Commit with a message
git commit -m "Added project notes and daily journal"

# (Optional) Push to remote
git push

Once a week is enough for most vaults. It takes 30 seconds.

Automate it with a cron job (Advanced)

If you want automatic daily backups, create a shell script:

Create the script:

nano ~/brain-dump-backup.sh

Add this content:

#!/bin/bash
cd ~/Library/Mobile\ Documents/iCloud~com~voicebraindump~app/Documents
git add .
git commit -m "Auto backup $(date +%Y-%m-%d)"
git push

Make it executable:

chmod +x ~/brain-dump-backup.sh

Add to crontab (runs daily at 11 PM):

crontab -e

Add this line:

0 23 * * * ~/brain-dump-backup.sh

Now your notes back up automatically every night.

What gets backed up

With the .gitignore above:

What stays out:

The last point is worth stating plainly: the app's durability machinery does not live in your notes folder. Ignoring .braindump/ costs you the app's internal recovery state, not your writing.

How to restore a note

Restore from recent history:

git log --oneline
# Shows recent commits

git show COMMIT_HASH:path/to/note.md
# Shows content of note at that commit

git checkout COMMIT_HASH -- path/to/note.md
# Restores that version

See what changed:

git diff HEAD~1 path/to/note.md
# Shows changes since last commit

Undo recent changes:

git reset --hard HEAD~1
# Rolls back to previous commit (use carefully!)

What Git covers that the app does not

Brain Dump protects a note during an editing session. If the file changes underneath the note you have open, the app verifies the change, reloads silently when your editor is clean, and shows both versions with a diff when it is not. When it preserves a version it writes a real file named <note name> conflicted copy <computer name> <timestamp>.md next to the original. Nothing is discarded to keep something else. Details in the conflict guide.

Git covers the cases that sit outside a session:

A deletion you notice a week later. The app has no opinion about a file you removed on purpose. Git does. Restore it with git checkout <commit> -- "Project Ideas".

An edit you regret after it saved. Autosave has already committed it to disk and to every synced device. git diff shows what changed and git checkout -- note.md puts the old text back.

The whole folder, off site. A private remote survives a lost laptop and a compromised iCloud account. The app's own recovery state does not, and is not meant to.

Combining Git with iCloud

iCloud and Git serve different purposes:

iCloud = sync across devices Your notes appear on iPhone, iPad, Mac automatically.

Git = version history and backup You can time-travel through changes and have an off-site copy.

Use both. They complement each other.

Troubleshooting

"Permission denied" when pushing Make sure you've set up SSH keys or use HTTPS with a personal access token. GitHub has docs on this.

Git is slow with many files If you have thousands of notes, Git might slow down. Consider archiving old notes to a separate repo.

Merge conflicts in notes Git is the second line here, not the first. If you edit a note in Brain Dump while another app writes the same file, Brain Dump resolves it in the app: it shows both versions with an inline diff and four choices, and preserves whichever side you did not keep as a separate file. By the time Git sees the folder, the decision is usually already made and both files are on disk. See the conflict guide for how that works and how to read the sheet.

Real Git merge conflicts in a notes vault come from committing the same file on two machines against different histories. Open the file, pick the text you want, git add, commit. Also worth checking: the quick checklist for recovering a missing note.

What about binary files? Git works best with text. If you save images or PDFs in your Brain Dump folder, they'll be versioned too, but they'll bloat the repository. Consider keeping media elsewhere.

The bottom line

Five minutes of setup, thirty seconds to commit. The one step people skip is the .gitignore, and skipping it is what makes the repository unusable a month later.

Related guides: