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
marfaCLI 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 localanswers 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:
marfa folders create --title Home --query '{"types":["core.note","core.file"],"filter":"tags contains \"home\""}' --defaults '{"tags":["home"]}'id 01a1f46f-bed0-7310-bb7c-840868eb64acKeep the ID on the id line for the next step.
Add your directory
marfa folders add ~/Documents/Home --folder 01a1f46f-bed0-7310-bb7c-840868eb64acthe 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-840868eb64acCheck 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
marfa folders push ~/Documents/Homethe server answered 7 change(s), creating 2 item(s)
1 file(s) writtenThe photo and the note are now items, tagged home. The note's file now starts with its details, and the directory holds:
.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 onChange 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.
- On the second computer, install the CLI and sign it in with your instance's address.
- Add a directory, naming the folder by its exact title or its ID, check the plan, and push:
marfa folders add ~/Documents/Home --folder Home
marfa folders push ~/Documents/Homethe 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) writtenTurn 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.