Sync and back up your Library

Years of notes shouldn't depend on one laptop. A failed drive, a stolen bag or a careless delete can happen to anyone, and sooner or later you'll want the same notes on a second Mac.

Terra doesn't run a sync service of its own, and it doesn't need one: a Library is a folder of ordinary files, so the backup and sync tools you already trust work with it. Terra adds one tool of its own, Versions, which keeps a history of your notes you can compare and restore, and can send that history to a Git server.

How it fits together

Versions answers "what did this note say last Tuesday?"; a backup covers everything else. They work well together.

Step 1Know what to keep

Everything that belongs to a Library is inside its folder: your notes, attachments and sidecars, and the hidden .terra folder, which holds your databases, templates, saved views, AI chats and the Library's settings. Back up the whole folder, hidden files included. How Terra stores your notes explains each part.

1. Click ⋯ (Library menu) at the bottom of the sidebar.

2. Choose Open in Finder to see where the folder is, or Copy library path to copy its location.

   

A few things live on each Mac, not in the Library: AI provider keys (in the Keychain), the Light, Dark or System appearance, Open at launch, and how you've arranged the sidebar and panes.

Step 2Back up with Time Machine

Time Machine, built into macOS, backs up your whole Mac to an external drive, hidden files included, so a Library in your home folder is covered. Turn it on in System Settings › General › Time Machine. Any backup app that copies folders works too.

To get back an older copy of a single note, open the Library folder in Finder and browse your Time Machine backups to the date you want. Restore the note's .md file, and its .terra.json file too if it has one. Terra notices the restored file and updates the note.

Step 3Share a Library through a cloud folder

To use the same Library on two Macs, keep it in a folder that iCloud Drive, Dropbox or OneDrive syncs.

1. Switch to another Library, or quit Terra.
2. In Finder, move the Library folder into your iCloud Drive, Dropbox or OneDrive folder.
3. Open Terra, press ⌘O, choose Open other… and pick the folder in its new place.
4. On your other Mac, wait until the folder has finished downloading, then open it the same way.

A few habits keep this smooth:

• Keep the files downloaded. If your sync service removes local copies to save space (such as iCloud's Optimize Mac Storage), Terra waits for each file to download, and the Library opens slowly.
• Let edits sync before switching Macs. If two Macs change the same note before syncing, the service may keep a "conflicted copy". It has the same id as the original, so Terra shows only one of the two. Combine them by hand in Finder and delete the copy.
• Connect AI providers on each Mac. Keys stay in each Mac's Keychain (see Ask your Library).

Step 4Turn on Versions

Versions uses git, the version-control tool programmers use, to keep a history of your notes. It's off until you turn it on.

1. Click Versions in the sidebar, under System.

2. Click Initialize version control.

   

3. macOS asks Initialize version control? Click Allow. Terra makes the Library a git repository and adds two small files, .gitignore and .gitattributes. Nothing is saved yet.

If the page says Version control unavailable instead, git isn't installed. Install it, then open the Library again.

Step 5Save a version

A version is a snapshot of every changed file in the Library. Terra never saves one on its own, so save whenever you reach a point you might want to come back to, such as the end of a work session.

1. On the Versions page, click Save version.

   

2. macOS asks Commit Library changes? Click Allow.

3. A message confirms it, for example Saved version 4e1a9c2. The version is named with the date and time.

Save version is greyed out when nothing has changed. A note with changes that aren't in a version yet shows Modified at the bottom of the note.

Step 6Compare and restore a note

1. Open the note, then click Versions in the toolbar (the clock at the top right). The Versions panel lists the note's saved versions, newest first, with how many lines each one added and removed.

2. Click a version to see what it changed, in a pane beside the note.

3. To go back to it, click ⋯ next to the version and choose Restore version. When macOS asks Restore this file version?, click Allow. A message says Restored to the save from and the date. View version shows it without changing anything.

   

Step 7Send versions to a Git server

To keep your history off this Mac, push your versions to a private repository on a Git host. Terra never asks for or stores git passwords, so you connect the repository once in Terminal.

1. Create an empty private repository on your Git host and copy its HTTPS or SSH address.

2. In Terra, choose Library menu › Copy library path.

3. In Terminal, run these lines, pasting your Library's path and your repository's address:

   cd "/Users/maya/Documents/Field Notes"
   git remote add origin git@github.com:maya/field-notes.git
   git push -u origin HEAD
   

   Sign in if git asks. The remote must be called origin, and its address must start with https:// or use SSH.

From then on, use the buttons on the Versions page:

• Push sends your saved versions. The number on it counts versions waiting to go. macOS asks Push Library commits?; click Allow, and a message says Pushed to upstream.
• Pull brings in versions saved elsewhere and updates your files. The number on it counts versions waiting to come in. macOS asks Pull and rewrite Library files?; click Allow.

To start on a second Mac, clone the repository in Terminal (git clone and the address), then open the folder in Terra with Open other…. Because .terra isn't in git, that Mac starts with Terra's own default templates and settings, and without your databases.

Go further

Turn version history off

If you don't use Versions in a Library, switch it off in Settings › Editor › Version history. Terra then stops saving versions and hides Versions and the Modified marker. Your existing history stays in the folder.

Resolve a conflict after pulling

If the same lines changed in two places, the message reads Pulled with conflicts — resolve the marked notes. Open each marked note in Markdown source, keep the text you want, delete git's <<<<<<<, ======= and >>>>>>> lines, then click Save version.

Troubleshooting

Push or Pull fails with a sign-in error

Terra never stores git credentials. In Terminal, go to the Library folder and run git push or git pull once, signing in when asked. Then try again in Terra.

"remote transport is not allowed; use HTTPS or SSH"

The origin remote has an address Terra won't use. Change it to an https:// address or an SSH one, such as git@github.com:maya/field-notes.git, with git remote set-url origin and the new address.

"no upstream configured for the current branch"

Run git push -u origin HEAD once in Terminal, in the Library folder.

"Version history is off. Turn it on in Settings → Editor."

Version history is switched off for this Library. Turn on Settings › Editor › Version history.

What's next

• Libraries — open, switch and move Libraries.
• How Terra stores your notes — every file a backup should include.
• Files and folders — the Trash, and getting deleted notes back.