Sync a folder

Keep a directory on your computer in step with your instance, so your files and notes are ordinary files you open in any app, on one computer or several.

A synced folder keeps a directory on your computer in step with your instance: a file you add there becomes an item, and a change on either side reaches the other. The folder lives on your instance; the directory is where its files sit on this computer.

  • You need the marfa CLI signed in to your instance, as the Quickstart sets it up.
  • For a second computer, you also need an address it reaches. An instance installed with --access local answers only on its own computer, so give it an address first.

The steps use a directory you already have, ~/Documents/Home, which holds a photo and a note.

Create the folder

Make the folder on your instance. Its query says which items it holds, here notes and files tagged home, and its defaults tag every new file home, so the folder holds only its own files:

Terminal
marfa folders create --title Home --query '{"types":["core.note","core.file"],"filter":"tags contains \"home\""}' --defaults '{"tags":["home"]}'
id                        01a1f46f-bed0-7310-bb7c-840868eb64ac

Keep the ID on the id line for the next step.

Add your directory

Terminal
marfa folders add ~/Documents/Home --folder 01a1f46f-bed0-7310-bb7c-840868eb64ac
the first sync of /Users/sam/Documents/Home will write and send nothing until you agree: 0 file(s) to write into the directory, 2 to send to the server
Go ahead? [y/N] y
/Users/sam/Documents/Home follows the folder 01a1f46f-bed0-7310-bb7c-840868eb64ac

Check the plan before you answer: here nothing is written into the directory, and the photo and the note are sent. If the numbers aren't what you expect, answer n, change the query with marfa folders update, as Change or stop syncing a folder shows, and run marfa folders confirm ~/Documents/Home when it's right.

If iCloud Drive syncs your Documents folder, folders add warns that a second program syncs the same files, and the two can overwrite each other's changes. Choose one:

  • Use a directory iCloud doesn't sync, such as ~/Marfa/Home.
  • Turn off Desktop & Documents Folders in System Settings > your name > iCloud > Drive. Your files stay in iCloud Drive, and your Mac gets new, empty folders.

It warns the same way for another cloud service's folder, network storage and a directory git tracks.

Run the first sync

Terminal
marfa folders push ~/Documents/Home
the server answered 7 change(s), creating 2 item(s)
1 file(s) written

The photo and the note are now items, tagged home. The note's file now starts with its details, and the directory holds:

beach.png
Packing list.md

.marfa holds the folder's settings and its record of each file: leave it in place.

Hold one project

A folder can hold one item and everything beneath it, such as a project and its tasks, where the project is itself a file in the directory. Name that file's path in beneath, relative to the directory:

marfa folders create --title Garden --query '{"types":["core.note"],"beneath":"Projects/Garden.md"}'

Until the file is an item, the folder holds nothing from your instance. The first sync sends the files, puts the file's item ID in place of the path, then brings in what lies beneath it. Until then, marfa folders status names the path, as does beneath_waiting in --json.

Keep it in step

push syncs once. To keep every folder in step while you work, turn on autostart, which runs a watch now and each time you log in:

marfa folders autostart on

Change a file in any app, or drop in another, and the watch sends it within seconds. Work with the files in a synced folder says what each change does.

Sync the folder on a second computer

Another directory can follow the same folder, and a change in one reaches the others.

  1. On the second computer, install the CLI and sign it in with your instance's address.
  2. Add a directory, naming the folder by its exact title or its ID, check the plan, and push:
Terminal
marfa folders add ~/Documents/Home --folder Home
marfa folders push ~/Documents/Home
the first sync of /Users/sam/Documents/Home will write and send nothing until you agree: 2 file(s) to write into the directory, 0 to send to the server
Go ahead? [y/N] y
2 file(s) written

Turn on autostart there too: each computer needs its own watch. Rename or move a file in one directory, and it moves in the others.

When two directories change a note at once, Marfa keeps both edits, as Sort out a conflicted copy shows. If a folder stops syncing, see Fix a folder.

On this page