# Work with the files in a synced folder (/use/work-with-folder-files)

Add, change, rename, delete, tag and attach the files and notes in a synced folder, and know what each change does to your items.



You and your agents work with a synced folder's files in any app. Each file is an item, and **each change you make reaches your instance at the next sync.** The examples follow the `Home` folder from [Sync a folder](/use/sync-a-folder).

## Files [#files]

A file such as a PDF, a photo or a spreadsheet holds the item's own bytes.

* **Add a file** and it becomes an item, titled with its file name, such as `water.pdf`, and tagged by the folder's defaults.
* **A file item saved elsewhere** gets the extension its type needs when its title has none: a PDF titled `Boiler receipt` is written as `Boiler receipt.pdf`, and keeps its title.
* **Put it in a subdirectory,** such as `Bills/water.pdf`, and it sits there in every directory that follows the folder.
* **Change a file** and the same item gets the change, as a new version.
* **Rename or move a file** and the item stays the same. Its title follows the new name only if it was the old file name, with or without the extension the folder added. A title you set yourself stays.
* **Names that differ only in case,** such as `Plan.md` and `plan.md`, are one name to a folder, as a Mac's disk compares them. On a disk that keeps them apart, such as most Linux disks, the folder keeps the file it holds and leaves the other unsent until you rename one.
* **Delete a file** and its item moves to the bin, where you can restore it. Many deletions at once wait for you, as [Fix a folder](/use/fix-a-folder#a-large-removal-waits) shows.

Tag a file's item from the CLI or an agent, with the ID that `marfa search` shows:

```bash
marfa items tags add 01a1f471-38e8-72d9-a656-9ada7595454a bills
```

Output:

```text
tagged 01a1f471-38e8-72d9-a656-9ada7595454a; it now has home, bills
```

## Notes [#notes]

A note is a Markdown file. **Add one with only a body,** such as `Ideas.md`, and it becomes a note titled `Ideas`. Marfa then writes its details at the top of the file:

```markdown title="Home/Ideas.md"
---
type: core.note
tier: library
tags:
  - home
title: Ideas
marfa_id: 01a1f471-38fb-76f9-81f4-efc639a26cd8
marfa_version: 1
---
Try the tram.
```

**Edit `title` and `tags`; leave the `marfa_` lines** to Marfa. Retitle a note anywhere and the next sync renames its file. A copy of a note under a new name becomes a new note, and two notes with the same title are written as two files, such as `Plan (2).md`.

## Files a folder leaves alone [#files-a-folder-leaves-alone]

A folder never takes in a file whose name a secret goes by, such as `.env` or `server.pem`, files your computer keeps for itself, such as `.DS_Store`, temporary files, or links. A push names each secret it leaves out:

```text
server.pem: not taken, because its name is one a secret goes by
```

A name that starts with a period is skipped too, unless the folder's settings include it. A hidden `.marfa-kept-<id>.tmp` file is one Marfa moved aside while it wrote: it settles it at the next scan, and never deletes it. [What a folder takes in](/reference/folder-rules#what-a-folder-takes-in) lists every name.

## Link to another item [#link-to-another-item]

Write a link in a note's body with double brackets, naming another item by its title or file name:

```markdown
Book the room from [[Hotel in Lisbon]], and pack from [[Packing list|the list]].
```

The text after `|` is what the note shows. A link follows a retitled note, and can name a note that doesn't exist yet. A name that fits several items connects to none, and the sync says so: rename one, or write the item's ID, as in `[[01a1f471-38fb-76f9-81f4-efc639a26cd8]]`.

## Attach a file to a note [#attach-a-file-to-a-note]

List the file on the note's `has-attachment` line:

```yaml
has-attachment:
  - "[[water.pdf]]"
```

**An attached file follows its note** to the bin and back. Take it off the line and the attachment ends, but the file stays an item. A picture from the folder that you embed in the body, such as `![](beach.png)`, shows in the note and links to the photo, but doesn't attach it.

[How a folder treats files](/reference/folder-rules) has every rule a folder follows.
