# Upload rules (/docs/library/rules)

Upload rules sort files by their name. A Space has an ordered list of them under **Upload rules**. When a file is uploaded, the **first** rule whose pattern matches its name puts it in the rule's folder and adds the rule's tags. A file no rule matches lands in the folder you upload to.

Editing the rules takes an admin, developer or editor role in the Space.

## Kinds of rule [#kinds-of-rule]

| Kind                   | Example                 | Matches                                                        |
| ---------------------- | ----------------------- | -------------------------------------------------------------- |
| **Pattern**            | `SS26_{campaign}_*.jpg` | The whole name: `{name}` captures a part, `*` matches anything |
| **Starts with**        | `SS26_`                 | Names that start with it                                       |
| **Contains**           | `_hero`                 | Names with it anywhere                                         |
| **Ends with**          | `.mp4`                  | Names that end with it                                         |
| **Regular expression** | `^(?<shoot>\d+)-`       | A JavaScript regular expression; named groups are captured     |

Case never matters. A pattern has at most 200 characters.

## Folders and tags [#folders-and-tags]

A rule puts files in a **folder**, **tags** them, or both. The folder is a path with `/` between folders, from the root: `Campaigns/Summer`. Folders that don't exist yet are made the first time a file needs them, matching existing names without case.

Both may use what the pattern captured. With the pattern `SS26_{campaign}_*.jpg`, the folder `Campaigns/SS26/{campaign}` and the tag `{campaign}`:

```
SS26_beach_jacket_01.jpg  →  Campaigns/SS26/beach, tagged beach
SS26_city_bag_04.jpg      →  Campaigns/SS26/city, tagged city
```

A rule can only use names its pattern captures, and has at most 20 tags. A Space has at most 50 rules.

## Testing a rule [#testing-a-rule]

**Try a file name** shows which rule takes a name, where the file would go, its tags and what the pattern captured, as you type; the rule that matches is marked in the list. Click a rule's pattern, folder or tags to change them. Drag a rule by its grip to change the order, or focus the grip and press Space, the arrow keys, then Space again; the first match wins, so put specific rules above general ones. A rule's menu duplicates or deletes it.

Nothing is saved until **Save rules**, in the bar that shows while the list has changes; **Discard** puts it back as saved. Leaving the page with changes asks first.

## When rules run [#when-rules-run]

- On every upload in the library, before the open folder is used.
- On [CSV imports](/docs/library/imports), for new files whose row names no folder.
- On an agent's `uploadFile`, unless it names a folder.
- On files already in the library only when you ask: select them and choose **Apply upload rules**. Matching files move to their rule's folder and gain its tags; their other tags stay.

Agents can read the rules with `listUploadRules`.