# Sync a folder (/use/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](/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](/run/address) first.

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

## Create the folder [#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:**

```bash
marfa folders create --title Home --query '{"types":["core.note","core.file"],"filter":"tags contains \"home\""}' --defaults '{"tags":["home"]}'
```

Output:

```text
id                        01a1f46f-bed0-7310-bb7c-840868eb64ac
```

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

## Add your directory [#add-your-directory]

```bash
marfa folders add ~/Documents/Home --folder 01a1f46f-bed0-7310-bb7c-840868eb64ac
```

Output:

```text
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](/use/change-or-stop-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 [#run-the-first-sync]

```bash
marfa folders push ~/Documents/Home
```

Output:

```text
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:

```text
Home/
  .marfa/
  beach.png
  Packing list.md
```

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

## Hold one project [#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:

```bash
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 [#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:

```bash
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](/use/work-with-folder-files) says what each change does.

## Sync the folder on a second computer [#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](/quickstart#install-marfa) and [sign it in](/run/sign-in-as-the-owner#sign-in-the-cli) with your instance's address.
2. Add a directory, naming the folder by its exact title or its ID, check the plan, and push:

```bash
marfa folders add ~/Documents/Home --folder Home
marfa folders push ~/Documents/Home
```

Output:

```text
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](/use/conflicts) shows. If a folder stops syncing, see [Fix a folder](/use/fix-a-folder).
