> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# .mesaignore

> Control which files mesa keeps locally vs. uploads to VCS.

Mesa uses a `.mesaignore` file to decide which files stay in local ephemeral storage and which are uploaded to
your repository. Files matching `.mesaignore` patterns are never uploaded — no blob upload, no tree mutation, no
ref update. They behave like normal files while the daemon is running but disappear on restart.

This is useful for editor scratch files (swap files, lock files), OS metadata (`.DS_Store`), and other files
that should never be committed.

## How it works

When the mesa daemon starts, it reads a single `.mesaignore` file and compiles the patterns into a matcher.
Every file write is checked against these patterns:

* **Match** → file is routed to ephemeral storage (local only, lost on restart)
* **No match** → file is uploaded to VCS (persisted in the repository)

The `.mesaignore` file uses [gitignore syntax](https://git-scm.com/docs/gitignore#_pattern_format) — the same
pattern format you already know from `.gitignore`.

## File location

Point Mesa at a `.mesaignore` file with the `MESA_MESAIGNORE_PATH` environment variable:

```bash theme={null}
MESA_MESAIGNORE_PATH=~/.config/mesa/.mesaignore mesa mount
```

If `MESA_MESAIGNORE_PATH` is not set, Mesa uses its built-in default rules.
(A `.mesaignore` next to a legacy `config.toml` is still picked up, but that
implicit lookup is deprecated along with config files.)

## Customizing

Edit the file directly:

```bash theme={null}
$EDITOR ~/.config/mesa/.mesaignore
```

Changes take effect on the next daemon restart (`mesa mount`). The file is the **sole source of ignore rules** —
there are no hidden defaults layered underneath. If you remove a pattern, that file type will be uploaded to VCS.

<Warning>
  The `.mesaignore` applies globally to **all repositories** mounted through mesa. For per-repo ignore rules,
  use the standard `.gitignore` inside each repository.
</Warning>

## Resetting to defaults

To restore the default patterns:

```bash theme={null}
mesa dump-default-mesaignore > ~/.config/mesa/.mesaignore
```

## Viewing current rules

To see what patterns are active:

```bash theme={null}
cat ~/.config/mesa/.mesaignore
```

To see the built-in defaults (useful for diffing against your customizations):

```bash theme={null}
mesa dump-default-mesaignore
```

## Safety guard

The pattern `!.mesaignore` is always enforced by the daemon, even if you remove it from your file. This prevents
you from accidentally ignoring your own configuration file.

## Fallback behavior

If no `.mesaignore` file exists on disk, the daemon falls back to compiled-in defaults (the same patterns written
on first run). To operate with no ignore rules, create an empty `.mesaignore` file.