{"owner":"juicedata","repo":"juicefs","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\nJuiceFS is a POSIX-compatible distributed file system written in Go\n(`module github.com/juicedata/juicefs`). A client coordinates a **metadata engine**\nand **object storage**, exposing POSIX (FUSE) and an S3 gateway, plus Java/Hadoop\n(`sdk/java/`) and Python (`sdk/python/`) SDKs.\n\nMetadata engine families under `pkg/meta/`:\n\n- **Redis** — `redisMeta` (`redis.go`); also KeyDB.\n- **SQL/DB** — `dbMeta` (`sql.go`): MySQL, PostgreSQL, SQLite.\n- **KV (TKV)** — `kvMeta` (`tkv.go`): TiKV, etcd, BadgerDB, FoundationDB.\n\n## Repository map\n\nEntry points: `main.go` (root) and `cmd/main.go` (CLI commands live in `cmd/`).\n\n| Path           | Responsibility                                                  |\n| -------------- | --------------------------------------------------------------- |\n| `cmd/`         | CLI subcommands (`mount`, `gateway`, `sync`, `format`, `gc`, …) |\n| `pkg/meta/`    | Metadata engine abstraction + per-engine implementations        |\n| `pkg/vfs/`     | Virtual filesystem layer (POSIX semantics)                      |\n| `pkg/fuse/`    | FUSE bindings (Linux/macOS); `pkg/winfsp/` for Windows          |\n| `pkg/fs/`      | High-level filesystem logic                                     |\n| `pkg/chunk/`   | Chunk / slice / block data management and caching               |\n| `pkg/object/`  | Object storage backend abstraction                              |\n| `pkg/gateway/` | S3-compatible gateway                                           |\n| `pkg/sync/`    | Data synchronization (`juicefs sync`)                           |\n| `pkg/acl/`     | POSIX ACL support                                               |\n| `docs/`        | Documentation: `docs/en/` (English), `docs/zh_cn/` (Chinese)    |\n\n## Build\n\n```sh\nmake juicefs                 # standard build -> ./juicefs\nSTATIC=1 make juicefs        # static binary (needs musl-gcc)\nmake BUILD=debug all         # debug build (-N -l)\nmake juicefs.lite            # minimal build, most backends disabled\nmake juicefs.ceph            # -tags ceph\nmake juicefs.fdb             # -tags fdb (FoundationDB)\n```\n\nLocal volume for manual testing (SQLite metadata):\n\n```sh\n./juicefs format sqlite3://test.db myjfs    # create a volume\n./juicefs mount  sqlite3://test.db /tmp/jfs # mount it\n```\n\n## Test\n\nUse the smallest target covering your change. Targets are in the `Makefile`\nand mirror CI (`.github/workflows/unittests.yml`).\n\n```sh\nmake test.meta.core          # ./pkg/meta/... core (no external services)\nmake test.meta.non-core      # Redis/PostgreSQL/etcd/KeyDB engine tests\nmake test.pkg                # all ./pkg/... except meta (-tags gluster)\nmake test.cmd                # ./cmd/... (needs MinIO env, runs under sudo)\nmake test.fdb                # FoundationDB tests (-tags fdb)\n```\n\n| Change scope       | Run                                                               |\n| ------------------ | ----------------------------------------------------------------- |\n| `pkg/meta/**`      | `make test.meta.core` (+ `test.meta.non-core` if engine-specific) |\n| `cmd/**`           | `make test.cmd`                                                   |\n| any other `pkg/**` | `make test.pkg`                                                   |\n\n- When fixing a bug, add a regression test that fails before the fix and passes after.\n- Group new test cases for the same module/category together; extend an existing test\n  rather than scattering new cases.\n\n## Lint & format\n\n- Run `go fmt` before committing.\n- Linting uses `golangci-lint` per `.golangci.yml`; pre-commit pins v1.52.2 and CI runs v2.6 (see `.github/workflows/verify.yml`).\n- Install hooks once with `pre-commit install` (config in `.pre-commit-config.yaml`).\n\n## Code style & license header\n\n- Follow [Effective Go](https://go.dev/doc/effective_go) and\n  [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).\n- Keep comments minimal; add only when necessary.\n- Every new `.go` file MUST start with the Apache 2.0 header (see `main.go` for the canonical template).\n\n## Version compatibility\n\n- Persistent metadata or serialization changes in `pkg/meta/{interface,redis,sql,tkv}.go`\n  must remain readable by new clients, and old clients must not silently drop new\n  fields when rewriting records.\n- When metadata fields change, review `pkg/meta/{dump,backup}.go`, `pkg/meta/*_bak.go`,\n  and `pb/backup.proto`. Released dump/load formats must remain readable; tolerate\n  unknown fields where feasible, reject unsupported formats explicitly, and never\n  silently lose correctness-critical data.\n- Evaluate mixed-version behavior for metadata features or semantic changes. If\n  unsafe, raise (never lower) `MinClientVersion` and enable the feature only after\n  old clients have exited.\n- FUSE option changes must preserve existing names and defaults. Review graceful\n  restart, `FuseOptions`, `StripOptions`, and old-config normalization in\n  `cmd/mount_unix.go`, `pkg/vfs/vfs.go`, and `pkg/fuse/fuse.go`.\n- Add compatibility tests, or explicitly report missing coverage during review.\n\n## Agent boundaries\n\n- Correctness first: this is a distributed file system; small changes can affect data\n  integrity. Do not invent APIs, defaults, or behavior — verify against the code, and\n  don't bypass safety checks.\n- Metadata-engine parity: a semantic change in `pkg/meta/` must behave identically\n  across all three families (Redis, SQL/DB, KV) and be covered by their shared tests.\n- Behavior changes need matching unit tests; user-facing changes update the docs.\n- Keep diffs minimal and scoped; avoid unrelated refactors or formatting-only churn.\n- Do not hand-edit generated code or vendored dependencies.\n- Match existing conventions in the file you are editing.\n- Confirm before destructive or hard-to-reverse actions (deleting files, force pushes,\n  schema/data changes).\n"},"files":{"AGENTS.md":"# AGENTS.md\n\nJuiceFS is a POSIX-compatible distributed file system written in Go\n(`module github.com/juicedata/juicefs`). A client coordinates a **metadata engine**\nand **object storage**, exposing POSIX (FUSE) and an S3 gateway, plus Java/Hadoop\n(`sdk/java/`) and Python (`sdk/python/`) SDKs.\n\nMetadata engine families under `pkg/meta/`:\n\n- **Redis** — `redisMeta` (`redis.go`); also KeyDB.\n- **SQL/DB** — `dbMeta` (`sql.go`): MySQL, PostgreSQL, SQLite.\n- **KV (TKV)** — `kvMeta` (`tkv.go`): TiKV, etcd, BadgerDB, FoundationDB.\n\n## Repository map\n\nEntry points: `main.go` (root) and `cmd/main.go` (CLI commands live in `cmd/`).\n\n| Path           | Responsibility                                                  |\n| -------------- | --------------------------------------------------------------- |\n| `cmd/`         | CLI subcommands (`mount`, `gateway`, `sync`, `format`, `gc`, …) |\n| `pkg/meta/`    | Metadata engine abstraction + per-engine implementations        |\n| `pkg/vfs/`     | Virtual filesystem layer (POSIX semantics)                      |\n| `pkg/fuse/`    | FUSE bindings (Linux/macOS); `pkg/winfsp/` for Windows          |\n| `pkg/fs/`      | High-level filesystem logic                                     |\n| `pkg/chunk/`   | Chunk / slice / block data management and caching               |\n| `pkg/object/`  | Object storage backend abstraction                              |\n| `pkg/gateway/` | S3-compatible gateway                                           |\n| `pkg/sync/`    | Data synchronization (`juicefs sync`)                           |\n| `pkg/acl/`     | POSIX ACL support                                               |\n| `docs/`        | Documentation: `docs/en/` (English), `docs/zh_cn/` (Chinese)    |\n\n## Build\n\n```sh\nmake juicefs                 # standard build -> ./juicefs\nSTATIC=1 make juicefs        # static binary (needs musl-gcc)\nmake BUILD=debug all         # debug build (-N -l)\nmake juicefs.lite            # minimal build, most backends disabled\nmake juicefs.ceph            # -tags ceph\nmake juicefs.fdb             # -tags fdb (FoundationDB)\n```\n\nLocal volume for manual testing (SQLite metadata):\n\n```sh\n./juicefs format sqlite3://test.db myjfs    # create a volume\n./juicefs mount  sqlite3://test.db /tmp/jfs # mount it\n```\n\n## Test\n\nUse the smallest target covering your change. Targets are in the `Makefile`\nand mirror CI (`.github/workflows/unittests.yml`).\n\n```sh\nmake test.meta.core          # ./pkg/meta/... core (no external services)\nmake test.meta.non-core      # Redis/PostgreSQL/etcd/KeyDB engine tests\nmake test.pkg                # all ./pkg/... except meta (-tags gluster)\nmake test.cmd                # ./cmd/... (needs MinIO env, runs under sudo)\nmake test.fdb                # FoundationDB tests (-tags fdb)\n```\n\n| Change scope       | Run                                                               |\n| ------------------ | ----------------------------------------------------------------- |\n| `pkg/meta/**`      | `make test.meta.core` (+ `test.meta.non-core` if engine-specific) |\n| `cmd/**`           | `make test.cmd`                                                   |\n| any other `pkg/**` | `make test.pkg`                                                   |\n\n- When fixing a bug, add a regression test that fails before the fix and passes after.\n- Group new test cases for the same module/category together; extend an existing test\n  rather than scattering new cases.\n\n## Lint & format\n\n- Run `go fmt` before committing.\n- Linting uses `golangci-lint` per `.golangci.yml`; pre-commit pins v1.52.2 and CI runs v2.6 (see `.github/workflows/verify.yml`).\n- Install hooks once with `pre-commit install` (config in `.pre-commit-config.yaml`).\n\n## Code style & license header\n\n- Follow [Effective Go](https://go.dev/doc/effective_go) and\n  [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).\n- Keep comments minimal; add only when necessary.\n- Every new `.go` file MUST start with the Apache 2.0 header (see `main.go` for the canonical template).\n\n## Version compatibility\n\n- Persistent metadata or serialization changes in `pkg/meta/{interface,redis,sql,tkv}.go`\n  must remain readable by new clients, and old clients must not silently drop new\n  fields when rewriting records.\n- When metadata fields change, review `pkg/meta/{dump,backup}.go`, `pkg/meta/*_bak.go`,\n  and `pb/backup.proto`. Released dump/load formats must remain readable; tolerate\n  unknown fields where feasible, reject unsupported formats explicitly, and never\n  silently lose correctness-critical data.\n- Evaluate mixed-version behavior for metadata features or semantic changes. If\n  unsafe, raise (never lower) `MinClientVersion` and enable the feature only after\n  old clients have exited.\n- FUSE option changes must preserve existing names and defaults. Review graceful\n  restart, `FuseOptions`, `StripOptions`, and old-config normalization in\n  `cmd/mount_unix.go`, `pkg/vfs/vfs.go`, and `pkg/fuse/fuse.go`.\n- Add compatibility tests, or explicitly report missing coverage during review.\n\n## Agent boundaries\n\n- Correctness first: this is a distributed file system; small changes can affect data\n  integrity. Do not invent APIs, defaults, or behavior — verify against the code, and\n  don't bypass safety checks.\n- Metadata-engine parity: a semantic change in `pkg/meta/` must behave identically\n  across all three families (Redis, SQL/DB, KV) and be covered by their shared tests.\n- Behavior changes need matching unit tests; user-facing changes update the docs.\n- Keep diffs minimal and scoped; avoid unrelated refactors or formatting-only churn.\n- Do not hand-edit generated code or vendored dependencies.\n- Match existing conventions in the file you are editing.\n- Confirm before destructive or hard-to-reverse actions (deleting files, force pushes,\n  schema/data changes).\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\nJuiceFS is a POSIX-compatible distributed file system written in Go\n(`module github.com/juicedata/juicefs`). A client coordinates a **metadata engine**\nand **object storage**, exposing POSIX (FUSE) and an S3 gateway, plus Java/Hadoop\n(`sdk/java/`) and Python (`sdk/python/`) SDKs.\n\nMetadata engine families under `pkg/meta/`:\n\n- **Redis** — `redisMeta` (`redis.go`); also KeyDB.\n- **SQL/DB** — `dbMeta` (`sql.go`): MySQL, PostgreSQL, SQLite.\n- **KV (TKV)** — `kvMeta` (`tkv.go`): TiKV, etcd, BadgerDB, FoundationDB.\n\n## Repository map\n\nEntry points: `main.go` (root) and `cmd/main.go` (CLI commands live in `cmd/`).\n\n| Path           | Responsibility                                                  |\n| -------------- | --------------------------------------------------------------- |\n| `cmd/`         | CLI subcommands (`mount`, `gateway`, `sync`, `format`, `gc`, …) |\n| `pkg/meta/`    | Metadata engine abstraction + per-engine implementations        |\n| `pkg/vfs/`     | Virtual filesystem layer (POSIX semantics)                      |\n| `pkg/fuse/`    | FUSE bindings (Linux/macOS); `pkg/winfsp/` for Windows          |\n| `pkg/fs/`      | High-level filesystem logic                                     |\n| `pkg/chunk/`   | Chunk / slice / block data management and caching               |\n| `pkg/object/`  | Object storage backend abstraction                              |\n| `pkg/gateway/` | S3-compatible gateway                                           |\n| `pkg/sync/`    | Data synchronization (`juicefs sync`)                           |\n| `pkg/acl/`     | POSIX ACL support                                               |\n| `docs/`        | Documentation: `docs/en/` (English), `docs/zh_cn/` (Chinese)    |\n\n## Build\n\n```sh\nmake juicefs                 # standard build -> ./juicefs\nSTATIC=1 make juicefs        # static binary (needs musl-gcc)\nmake BUILD=debug all         # debug build (-N -l)\nmake juicefs.lite            # minimal build, most backends disabled\nmake juicefs.ceph            # -tags ceph\nmake juicefs.fdb             # -tags fdb (FoundationDB)\n```\n\nLocal volume for manual testing (SQLite metadata):\n\n```sh\n./juicefs format sqlite3://test.db myjfs    # create a volume\n./juicefs mount  sqlite3://test.db /tmp/jfs # mount it\n```\n\n## Test\n\nUse the smallest target covering your change. Targets are in the `Makefile`\nand mirror CI (`.github/workflows/unittests.yml`).\n\n```sh\nmake test.meta.core          # ./pkg/meta/... core (no external services)\nmake test.meta.non-core      # Redis/PostgreSQL/etcd/KeyDB engine tests\nmake test.pkg                # all ./pkg/... except meta (-tags gluster)\nmake test.cmd                # ./cmd/... (needs MinIO env, runs under sudo)\nmake test.fdb                # FoundationDB tests (-tags fdb)\n```\n\n| Change scope       | Run                                                               |\n| ------------------ | ----------------------------------------------------------------- |\n| `pkg/meta/**`      | `make test.meta.core` (+ `test.meta.non-core` if engine-specific) |\n| `cmd/**`           | `make test.cmd`                                                   |\n| any other `pkg/**` | `make test.pkg`                                                   |\n\n- When fixing a bug, add a regression test that fails before the fix and passes after.\n- Group new test cases for the same module/category together; extend an existing test\n  rather than scattering new cases.\n\n## Lint & format\n\n- Run `go fmt` before committing.\n- Linting uses `golangci-lint` per `.golangci.yml`; pre-commit pins v1.52.2 and CI runs v2.6 (see `.github/workflows/verify.yml`).\n- Install hooks once with `pre-commit install` (config in `.pre-commit-config.yaml`).\n\n## Code style & license header\n\n- Follow [Effective Go](https://go.dev/doc/effective_go) and\n  [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).\n- Keep comments minimal; add only when necessary.\n- Every new `.go` file MUST start with the Apache 2.0 header (see `main.go` for the canonical template).\n\n## Version compatibility\n\n- Persistent metadata or serialization changes in `pkg/meta/{interface,redis,sql,tkv}.go`\n  must remain readable by new clients, and old clients must not silently drop new\n  fields when rewriting records.\n- When metadata fields change, review `pkg/meta/{dump,backup}.go`, `pkg/meta/*_bak.go`,\n  and `pb/backup.proto`. Released dump/load formats must remain readable; tolerate\n  unknown fields where feasible, reject unsupported formats explicitly, and never\n  silently lose correctness-critical data.\n- Evaluate mixed-version behavior for metadata features or semantic changes. If\n  unsafe, raise (never lower) `MinClientVersion` and enable the feature only after\n  old clients have exited.\n- FUSE option changes must preserve existing names and defaults. Review graceful\n  restart, `FuseOptions`, `StripOptions`, and old-config normalization in\n  `cmd/mount_unix.go`, `pkg/vfs/vfs.go`, and `pkg/fuse/fuse.go`.\n- Add compatibility tests, or explicitly report missing coverage during review.\n\n## Agent boundaries\n\n- Correctness first: this is a distributed file system; small changes can affect data\n  integrity. Do not invent APIs, defaults, or behavior — verify against the code, and\n  don't bypass safety checks.\n- Metadata-engine parity: a semantic change in `pkg/meta/` must behave identically\n  across all three families (Redis, SQL/DB, KV) and be covered by their shared tests.\n- Behavior changes need matching unit tests; user-facing changes update the docs.\n- Keep diffs minimal and scoped; avoid unrelated refactors or formatting-only churn.\n- Do not hand-edit generated code or vendored dependencies.\n- Match existing conventions in the file you are editing.\n- Confirm before destructive or hard-to-reverse actions (deleting files, force pushes,\n  schema/data changes).\n","category":"root","tokens":1464}]}