All chapters

  1. Getting started

    1. Start here
    2. Install, update & first launch
    3. Bring your notes in
    4. Your vault & the window

  2. Daily work

    1. Writing & the editor
    2. The Note Inspector & history
    3. Capturing ideas
    4. Today & daily notes
    5. Tasks
    6. Minutes: recording meetings

  3. Find and understand

    1. Finding & connecting notes
    2. Setting up AI
    3. Ask Header
    4. AI writing tools: Review, Refactor & the selection assistant
    5. Lenses
    6. Atlas
    7. Mindprint, Review & Retro

  4. Research and publish

    1. Research & the Reading Room
    2. Manuscripts
    3. Boards

  5. Protect your notes

    1. Trust, safety & privacy
    2. Sync & backup

  6. Reference

    1. Header across macOS
    2. Settings
    3. Keyboard shortcuts
    4. Help, feedback & FAQ
Your notes on every Mac

Sync & backup

Header has no sync server of its own. Your vault is a folder, so the service that already syncs your files can sync your notes too. Header helps when that service leaves conflict copies behind, can carry each note's history along, and in the download version can keep a Git backup of the whole vault.

Keep your vault in a synced folder

iCloud Drive, Dropbox, Google Drive or any service with a local folder

To use the same notes on your desk Mac and your laptop, put the vault folder inside a folder your sync service already watches. Header reads and writes Markdown there, and your provider handles the syncing.

  1. Choose File → Add Vault… (⇧⌘O).
  2. Pick or create a folder inside iCloud Drive, Dropbox or another synced location, for example iCloud Drive/Notes.
  3. On your other Mac, add the same folder as a vault once it has synced there.

You can also change the current vault in Settings → General → Vault with Choose....

Find it File → Add Vault… ⇧⌘O · Settings → Sync & Backup → Cloud Folder Sync & Backup

Sync Recovery Safety

When a note was edited on two Macs at once

If you edit Weekly plan.md on two Macs before they have synced, the service has to keep both versions. Header looks for the results and offers to merge them:

  • iCloud Drive keeps conflicting versions without adding a file. Header reads those versions directly and shows a bar such as iCloud kept two versions of “Weekly plan”.
  • Dropbox, Nextcloud, Syncthing and Google Drive add a conflict copy next to the note. Header recognises their file names and offers a review.

Click Review to see what the other Mac changed, region by region. Parts that only the other Mac changed come pre-ticked. Parts both Macs changed are marked and left for you to pick. Then choose one of:

ButtonResult
Keep MineKeeps this Mac's version.
Keep OtherTakes the other Mac's version.
Apply MergeUses the regions you ticked from the other version.

Header saves both versions to the note's history before it changes anything. Afterwards a conflict-copy file goes to the Trash rather than being deleted. For iCloud, only the conflict record is cleared.

The Sync Recovery window

Some files can't be paired automatically, for example a conflict copy whose original is missing, or a copy of a PDF. These wait under Needs your confirmation, where you can Open or Reveal each one, Choose Original for a text file, keep both, or dismiss it. Header won't merge, replace or delete non-text files.

OneDrive doesn't mark its duplicates clearly, so Header doesn't guess. Click Scan for Possible Duplicates at the bottom of the window to look for them on demand. The scan never changes a file.

Find it Settings → Sync & Backup → Open Sync Recovery… · or Review on the bar above your notes

History that travels with the vault

Time Travel on every Mac

With Sync note history across your devices turned on, which is the default, Header stores each note's Time Travel history in the vault's .header/history/ folder. It syncs along with your notes, so you can restore a version on your laptop that you saved on your desk Mac. Turn it off to keep history only on this Mac.

Find it Settings → Sync & Backup → History & local sync

Git backup

Versioned history of the whole vault · download version only

Git keeps a dated record of every change to every file in the vault, and with a remote such as a private GitHub repository it gives you a copy off this Mac. It's in the version you download from headernotes.com, not the TestFlight build. Your Mac needs Git installed; if it isn't, Header suggests installing Apple's Command Line Tools or Git from Homebrew.

Start a backup

Choose File → Back Up Vault with Git…. Header creates a Git repository in the vault and makes a first backup commit. The Remote URL (optional) field can stay blank for a backup that stays on this Mac. Click Start Backup.

Connect GitHub

  1. In Settings → Git, click Sign In to GitHub…. Header shows a one-time code; click Copy, then Open GitHub and enter it there.
  2. To use a repository you already have, click Choose Repository…. Header connects only an empty repository and refuses one that already has content.
  3. To start a new one, click Create a New Repository on GitHub…. Header doesn't create it for you. The guide walks you through it: Create on GitHub… opens GitHub with a suggested name so you can create an empty private repository, Give Header Access… lets you grant access to it, and Check Again finds it so you can click Use This Repository.

If GitHub hasn't given Header access to any repository yet, Settings shows Give Header access to a repository first.

After setup

With Enable Git sync on, Header backs up about 75 seconds after you stop making changes in Header, and once after it opens the vault. To back up now, use File → Git Sync Active Vault, Sync Active Vault Now in Settings → Git, or Sync with Git Now in the command palette. Settings shows when the last backup ran. Header never force-pushes and never merges diverged history on its own.

Other Git hosts

Any remote works through Add Remote… or the setup sheet. Header uses your own Git setup, such as your SSH keys. It never prompts for or stores a Git password, and it refuses a remote URL with credentials written into it. Your GitHub sign-in is kept in the Keychain and reaches only the repositories you grant.

A private GitHub repository controls who can see your notes, but it isn't end-to-end encrypted: GitHub stores them as readable text. Locked notes stay encrypted. Files over GitHub's 100 MB limit are left out of the backup, and Settings lists them.
Find it File → Back Up Vault with Git… · Settings → Git · File → Git Sync Active Vault

Backups, in plain terms

Sync is not the same as a backup

A synced folder copies your changes everywhere, including mistakes, so a note you delete on one Mac disappears from the others too. Time Travel helps with a single note, but its history is stored in the vault or on this Mac. For a real backup, keep a copy somewhere else:

  • Time Machine, or any backup tool you already use. Your notes are ordinary files, so it backs them up like everything else.
  • Git with a remote, as described above. A local Git repository without a remote sits on the same disk as your notes.