.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

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

.ftlignore

# 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

# 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

.ftlignore (Example 1: Python project)

# Python
__pycache__
*.pyc
.pytest_cache
.mypy_cache
.ruff_cache
venv
.venv

# Build
dist
build
*.egg-info

# IDE
.idea
.vscode

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:

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

.ftlignore

data/
datasets/
*.csv
*.parquet

Ignoring Generated Code

.ftlignore

generated/
*.generated.ts
proto/

Ignoring Documentation Builds

.ftlignore

docs/_build/
site/
.docusaurus/

Ignoring Temporary Files

.ftlignore

tmp/
temp/
*.tmp
*.swp

Debugging Ignored Files

To see which files would be included in a snapshot:

# Create a test snapshot
ftl code 'test'

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

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

Limitations

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:

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