> ## Documentation Index
> Fetch the complete documentation index at: https://vvennela-ftl-18-95.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# .ftlignore File Format

> Control which files are excluded from snapshots using .ftlignore

## Overview

The `.ftlignore` file controls which files and directories are excluded when FTL creates project snapshots. It works similarly to `.gitignore`.

## File Location

Place `.ftlignore` in your project root, next to `.ftlconfig`:

```
your-project/
├── .ftlconfig
├── .ftlignore
├── .env
└── src/
```

## Always-Ignored Patterns

FTL automatically excludes these directories from all snapshots, even if not listed in `.ftlignore`:

```
node_modules
.git
__pycache__
.env
venv
.venv
dist
build
.next
.ftl
.pytest_cache
.mypy_cache
.ruff_cache
.coverage
coverage
htmlcov
```

Source: `ftl/ignore.py:3-20`

> [!NOTE]
>
> The `.env` file is **always ignored** to prevent your real credentials from entering the sandbox.

## Syntax

### Basic Rules

* One pattern per line
* Lines starting with `#` are comments
* Blank lines are ignored
* Patterns are matched as directory/file names (not globs)

### Example File

```bash .ftlignore theme={null}
# Build artifacts
target
out

# IDE files
.idea
.vscode

# OS files
.DS_Store
Thumbs.db

# Test output
test-results
__snapshots__
```

## Pattern Matching

FTL uses **directory/file name matching**, not full glob patterns. A pattern matches if it appears anywhere in the path.

### How Matching Works

```python theme={null}
# Pattern: "tmp"

Matches:
  tmp/
  build/tmp/
  src/tmp/cache/
  outputs/tmp.log  # Any path component named "tmp"

Does not match:
  temporary/
  src/tmpfile.txt  # "tmp" must be a complete path component
```

Matching logic: `ftl/ignore.py:41-46`

### Examples

```bash .ftlignore (Example 1: Python project) theme={null}
# Python
__pycache__
*.pyc
.pytest_cache
.mypy_cache
.ruff_cache
venv
.venv

# Build
dist
build
*.egg-info

# IDE
.idea
.vscode
```

```bash .ftlignore (Example 2: Node.js project) theme={null}
# Node.js
node_modules
npm-debug.log
yarn-error.log

# Build
dist
build
.next
out

# Testing
coverage
.nyc_output

# IDE
.idea
.vscode
```

```bash .ftlignore (Example 3: Monorepo) theme={null}
# Shared
node_modules
.git

# Build outputs
dist
build
target
out

# Logs
logs
*.log

# Caches
.cache
.turbo
```

## Loading Process

FTL loads ignore patterns in two steps:

1. **Built-in patterns** - Always-ignored directories (see above)
2. **`.ftlignore` file** - Additional project-specific patterns

The final ignore set is the union of both:

```python theme={null}
ignore_set = ALWAYS_IGNORE | load_ftlignore(project_path)
```

Loading logic: `ftl/ignore.py:23-38`

## Snapshot Behavior

When FTL creates a snapshot:

1. Walks the project directory tree from the root
2. For each path, checks if any component matches the ignore set
3. Skips the entire subtree if a match is found
4. Copies non-ignored files to `~/.ftl/snapshots/<id>/` (local) or S3 (if configured)

Matching check: `ftl/ignore.py:41-46`

## Common Use Cases

### Ignoring Large Datasets

```bash .ftlignore theme={null}
data/
datasets/
*.csv
*.parquet
```

### Ignoring Generated Code

```bash .ftlignore theme={null}
generated/
*.generated.ts
proto/
```

### Ignoring Documentation Builds

```bash .ftlignore theme={null}
docs/_build/
site/
.docusaurus/
```

### Ignoring Temporary Files

```bash .ftlignore theme={null}
tmp/
temp/
*.tmp
*.swp
```

## Debugging Ignored Files

To see which files would be included in a snapshot:

```bash theme={null}
# Create a test snapshot
ftl code 'test'

# Inspect snapshot contents
ls -la ~/.ftl/snapshots/<snapshot-id>/
```

Snapshot location: `~/.ftl/snapshots/<project-hash>/<id>/`

## Limitations

> [!WARNING]
>
> **Current limitations:**
>
> * No glob patterns (`*.txt`, `**/*.log`) - only exact name matches
> * No negation (`!important.log`) to un-ignore files
> * No directory-only syntax (`dir/` vs `dir`)
>
> All matching is based on path component names.

## Best Practices

1. **Exclude build artifacts** - These can be regenerated by the agent if needed
2. **Exclude dependencies** - Use the `setup` hook in `.ftlconfig` to install them
3. **Exclude large files** - Speeds up snapshot creation and reduces storage
4. **Keep sensitive files out** - `.env` is always ignored, but add others if needed

## Integration with Rsync

For local snapshots, FTL uses `rsync` with exclude patterns generated from the ignore set:

```bash theme={null}
rsync -a \
  --exclude='node_modules' \
  --exclude='.git' \
  --exclude='__pycache__' \
  # ... (all ignore patterns)
  /path/to/project/ ~/.ftl/snapshots/<id>/
```

For S3 snapshots, files are filtered before creating the tarball.

## Source Reference

* Always-ignore list: `ftl/ignore.py:3-20`
* Load .ftlignore: `ftl/ignore.py:23-33`
* Build ignore set: `ftl/ignore.py:36-38`
* Should ignore check: `ftl/ignore.py:41-46`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.