# TigerFS Documentation

> Reference for mounting PostgreSQL as a versioned filesystem: CLI, dot-directory capabilities, file-first workspaces, data-first pipelines, agent skills, and platform adapters (FUSE/NFS).

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3)
- [GitHub repository](https://github.com/timescale/tigerfs)

## Repository

- Repository: timescale/tigerfs

- Generated: 2026-06-03T08:03:54.777Z
- Updated: 2026-06-03T08:04:10.955Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 25

## Pages

- [Overview](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/01-overview.md): What TigerFS exposes (mount + dot-directories), file-first vs data-first entry paths, runtime assumptions (PostgreSQL, FUSE/NFS), and the first routes to read.
- [Installation](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/02-installation.md): Install paths (curl installer, go install, releases), platform prerequisites (Linux FUSE, macOS NFS, Docker), and verification commands.
- [Quickstart](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/03-quickstart.md): First successful mount (postgres:// or tiger:), explore with ls/cat, demo.sh workflows, and expected success signals.
- [Filesystem as API](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/04-filesystem-as-api.md): Mount hierarchy, schema/table/row/column path model, dot-directory control surface, and how fs.Operations maps paths to SQL.
- [File-first and data-first](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/05-file-first-and-data-first.md): When a mount path is a workspace vs a table, .build/.format vs raw tables, .tables/ backing schema, and mode detection rules.
- [Capability directories](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/06-capability-directories.md): Pipeline path grammar (.by, .filter, .order, .first, .last, .export), chaining limits, SQL pushdown, and PathType resolution in path.go.
- [Synthesized apps](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/07-synthesized-apps.md): Workspace creation via .build/, markdown/plaintext formats, backing tables in tigerfs schema, views, and column/frontmatter mapping.
- [Consistency and caching](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/08-consistency-and-caching.md): Cross-mount read freshness (no content cache), metadata/stat/path cache TTLs, invalidation on writes, and pipeline cache key isolation.
- [Platform backends](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/09-platform-backends.md): Linux FUSE vs macOS in-process NFS (go-nfs), write/commit model on NFS, mount registry, and adapter delegation to fs.Operations.
- [File-first workspaces](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/10-file-first-workspaces.md): Create workspaces, read/write markdown and plaintext, directories as state, frontmatter semantics, and backing-table access via .tables/.
- [Data-first exploration](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/11-data-first-exploration.md): Row/column reads, index navigation (.by), pagination (.first/.last/.sample), PATCH writes, import/export, and large-table safety limits.
- [History, savepoints, and undo](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/12-history-savepoints-and-undo.md): Enable history on workspaces, .history/.log paths, savepoint JSON, .undo preview/apply, per-user filters, auto-savepoints, and migration boundaries.
- [Agent skills](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/13-agent-skills.md): Bundled skills/tigerfs pack, install-time staging to agent config dirs, SKILL.md navigation (files, data, ops, recipes), and mount-time copy behavior.
- [Cloud backends](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/14-cloud-backends.md): tiger: and ghost: prefix resolution, create/fork/list flows, default_backend config, and Tiger CLI credential requirements.
- [DDL staging](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/15-ddl-staging.md): .create/.modify/.delete staging dirs, sql/.test/.commit control files, index DDL via .indexes/, grace period, and errno on validation failures.
- [CLI reference](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/16-cli-reference.md): All cobra commands (mount, unmount, stop, status, info, list, create, fork, migrate, test-connection, config, version), flags, and argument patterns.
- [Configuration reference](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/17-configuration-reference.md): Config struct fields, ~/.config/tigerfs/config.yaml, TIGERFS_* env vars, precedence, TLS enforcement, and mount-specific overrides.
- [Data formats reference](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/18-data-formats-reference.md): TSV, CSV, JSON, YAML row encoding, PATCH semantics, NULL representation, type extensions (.txt/.json/.bin), and binary_encoding options.
- [Connection reference](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/19-connection-reference.md): postgres:// URIs, PG* env vars, password_command, .pgpass, sslmode=require rules, localhost exemptions, and pool settings.
- [Error codes](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/20-error-codes.md): fs.ErrorCode to POSIX errno mapping, structured zap hints on failure, constraint violations, and reading stderr when tools report EINVAL/EACCES.
- [Demo environment](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/21-demo-environment.md): scripts/demo workflows (Docker vs macOS native), seed data, demo.sh start/shell/stop, and sample exploration commands.
- [Workflow recipes](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/22-workflow-recipes.md): Copy-paste file-first patterns: kanban (todo/doing/done + mv), knowledge base, session context, from skills/tigerfs/recipes.md.
- [Migrate workspaces](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/23-migrate-workspaces.md): tigerfs migrate --describe/--dry-run, history-format migrations, pre-boundary undo EPERM, and release verification against test/integration migrate tests.
- [Develop and test](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/24-develop-and-test.md): Build commands, go test ./... and integration testcontainers, pre-commit checks, stress runner, and release-process checklist.
- [Troubleshooting](https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/pages/25-troubleshooting.md): Stale mounts, force unmount, NFS monotonicity warnings in stress runs, logging --debug, .refresh metadata clear, and common errno recovery.

## Source Files

- `.github/workflows/test.yml`
- `.goreleaser.yaml`
- `CHANGELOG.md`
- `CLAUDE.md`
- `cmd/tigerfs/main.go`
- `docs/adr/001-fuse-library.md`
- `docs/adr/003-ddl-staging-pattern.md`
- `docs/adr/013-backend-prefix-scheme.md`
- `docs/adr/014-query-reduction-caching.md`
- `docs/adr/016-undo-and-recovery.md`
- `docs/adr/019-undo-boundary-via-metadata-table.md`
- `docs/data-first.md`
- `docs/file-first.md`
- `docs/history.md`
- `docs/quickstart.md`
- `docs/release-process.md`
- `docs/spec.md`
- `go.mod`
- `internal/tigerfs/backend/ghost.go`
- `internal/tigerfs/backend/resolve.go`
- `internal/tigerfs/backend/tiger.go`
- `internal/tigerfs/cmd/cmd_test.go`
- `internal/tigerfs/cmd/config.go`
- `internal/tigerfs/cmd/create.go`
- `internal/tigerfs/cmd/fork.go`
- `internal/tigerfs/cmd/migrate.go`
- `internal/tigerfs/cmd/mount.go`
- `internal/tigerfs/cmd/root.go`
- `internal/tigerfs/cmd/stop.go`
- `internal/tigerfs/cmd/test_connection.go`
- `internal/tigerfs/cmd/unmount.go`
- `internal/tigerfs/config/config_test.go`
- `internal/tigerfs/config/config.go`
- `internal/tigerfs/db/connection.go`
- `internal/tigerfs/db/password.go`
- `internal/tigerfs/db/pipeline.go`
- `internal/tigerfs/db/query.go`
- `internal/tigerfs/db/tls.go`
- `internal/tigerfs/format/convert.go`
- `internal/tigerfs/format/csv.go`
- `internal/tigerfs/format/json.go`
- `internal/tigerfs/format/yaml.go`
- `internal/tigerfs/fs/auto_savepoint_test.go`
- `internal/tigerfs/fs/build.go`
- `internal/tigerfs/fs/constants.go`
- `internal/tigerfs/fs/context.go`
- `internal/tigerfs/fs/ddl.go`
- `internal/tigerfs/fs/errors_test.go`
- `internal/tigerfs/fs/errors.go`
- `internal/tigerfs/fs/extensions.go`
- `internal/tigerfs/fs/history.go`
- `internal/tigerfs/fs/metadata_cache.go`
- `internal/tigerfs/fs/operations.go`
- `internal/tigerfs/fs/path_cache.go`
- `internal/tigerfs/fs/path.go`
- `internal/tigerfs/fs/staging.go`
- `internal/tigerfs/fs/synth/build.go`
- `internal/tigerfs/fs/synth/format.go`
- `internal/tigerfs/fs/synth/markdown.go`
- `internal/tigerfs/fs/synth/plaintext.go`
- `internal/tigerfs/fs/undo_boundary_test.go`
- `internal/tigerfs/fs/undo.go`
- `internal/tigerfs/fs/write.go`
- `internal/tigerfs/fuse/adapter.go`
- `internal/tigerfs/fuse/control_files.go`
- `internal/tigerfs/logging/logging.go`
- `internal/tigerfs/mount/registry.go`
- `internal/tigerfs/nfs/handler.go`
- `internal/tigerfs/nfs/mount_darwin.go`
- `README.md`
- `scripts/demo/demo.sh`
- `scripts/demo/init.sql`
- `scripts/demo/README.md`
- `scripts/demo/seed.sh`
- `scripts/install.sh`
- `scripts/pre-commit`
- `scripts/test-install.sh`
- `skills/tigerfs/data.md`
- `skills/tigerfs/files.md`
- `skills/tigerfs/ops.md`
- `skills/tigerfs/recipes.md`
- `skills/tigerfs/SKILL.md`
- `test/integration/crud_test.go`
- `test/integration/ddl_test.go`
- `test/integration/demo_data.go`
- `test/integration/format_test.go`
- `test/integration/fs_operations_test.go`
- `test/integration/main_test.go`
- `test/integration/migrate_test.go`
- `test/integration/pipeline_test.go`
- `test/integration/setup.go`
- `test/integration/synthesized_test.go`
- `test/integration/undo_test.go`
- `test/stress/README.md`