> The Mac app keeps a collection in step both ways with a folder of Markdown files, so any editor or coding agent can write memos. You decide conflicts.

# Sync a collection to a folder on your Mac

Folder sync turns a collection into a folder of Markdown files on your Mac, kept in step both ways. Write in whatever editor you like, point a coding agent at the folder, or drop in files from another tool, and the memos update in Fieldwerk. Edit a memo in Fieldwerk and the file updates. When both change at once, nothing is overwritten: Fieldwerk keeps both and asks you which to keep.

Folder sync comes with the [Fieldwerk Mac app](https://help.fieldwerk.ai/siac5eoxz0/install-the-fieldwerk-mac-app.md). The Mac app is in preview. To ask for access, email [team@fieldwerk.ai](mailto:team@fieldwerk.ai).

## Set up a folder

1. Open the Mac app's **Settings…** and choose **Sync**.

2. If asked, click **Sign in** to connect this Mac.

3. Under **Collections**, pick the collection to sync.

4. Under **Folder on this Mac**, click **Choose…** and pick a folder.

5. Click **Start syncing**.

Each collection can sync to its own folder. Use **Open** to show a folder in Finder, or **Change…** to pick a different one.

A good habit is to sync the collection your tools work in most, such as a client's memos or a project's specs, and leave the rest in the browser.

## Keep syncing in the background

Turn on **Keep syncing when Fieldwerk is closed** under **Background**. Sync then runs whenever you're logged in to your Mac, even with the app closed, so a file saved at any time reaches Fieldwerk.

## See a file's state in Finder

After each sync, files in the folder carry a Finder tag when something needs attention: red **Conflict** when both sides changed, orange **Not synced** when a local edit hasn't been accepted yet, grey **Skipped** for a file you've excluded. Tags clear when the state does, and tags you applied yourself are never touched.

## When both sides changed

If a memo changed in Fieldwerk and in the folder since they last matched, nothing is overwritten. The menu bar icon shows how many changes need you, and the **Needs your decision** window explains each one. Click **Compare versions** to see **Yours** beside the **Remote copy**, then choose:

- **Keep mine**: your file becomes the memo. The Fieldwerk version stays in the memo's history.

- **Keep remote**: the Fieldwerk version replaces your file. Your copy goes to the Mac's Trash.

- **Keep both**: your file becomes the memo and the Fieldwerk version becomes a separate memo.

## When files are deleted from the folder

If several files disappear from the folder at once, Fieldwerk holds the deletions and asks first. Choose **Keep them** to bring the files back on the next sync, or **Delete in Fieldwerk** to move the memos to trash, where they can still be restored.

## Use the command line

The app includes a `fieldwerk` command for the terminal, so sync can run on a machine with no window open, or inside a script. It lives inside the app and isn't added to your PATH; link it once:

```
ln -s /Applications/Fieldwerk.app/Contents/MacOS/fieldwerk /usr/local/bin/fieldwerk
```

| Command | Does |
|---|---|
| `fieldwerk login` | Connects this Mac to your account |
| `fieldwerk setup` | Picks workspaces, collections and folders |
| `fieldwerk sync` | Syncs both ways once |
| `fieldwerk push` | Sends your changes up only |
| `fieldwerk watch` | Keeps syncing until you stop it |
| `fieldwerk status` | Shows what a sync would do, without doing it |
| `fieldwerk review` | Lists and resolves changes that need a decision |
| `fieldwerk autostart on` | Syncs in the background when you log in |
| `fieldwerk exclude <file>` | Stops syncing one file |
| `fieldwerk restore` | Re-adds files that lost their memo as new memos |
| `fieldwerk activity` | Shows recent sync activity |
| `fieldwerk logout` | Disconnects this Mac |

Only one sync runs at a time per folder. If the app is already syncing it, a second `fieldwerk watch` says so and stops.

To keep a collection in a GitHub repo instead, see [Sync a collection with a GitHub repo](https://help.fieldwerk.ai/pxb7sp8ilx/sync-a-collection-with-a-github.md).