fdl-cli 0.28.0__tar.gz → 0.30.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (116) hide show
  1. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/CHANGELOG.md +85 -0
  2. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/PKG-INFO +1 -1
  3. fdl_cli-0.30.0/cases/retention.json +325 -0
  4. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/getting-started.md +2 -0
  5. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/guides/mirrors.md +1 -1
  6. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/internals/inside-a-repository.md +1 -1
  7. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/getting-started.md +2 -0
  8. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/guides/mirrors.md +1 -1
  9. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/internals/inside-a-repository.md +1 -1
  10. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/reference/cli.md +24 -8
  11. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/reference/python.md +5 -4
  12. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/data-files.md +31 -5
  13. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/meta.ts +1 -1
  14. fdl_cli-0.30.0/docs/ja/spec/retention-cases.md +42 -0
  15. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/versions.md +1 -1
  16. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/reference/cli.md +24 -8
  17. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/reference/python.md +6 -5
  18. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/data-files.md +31 -5
  19. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/meta.ts +1 -1
  20. fdl_cli-0.30.0/docs/spec/retention-cases.md +42 -0
  21. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/versions.md +1 -1
  22. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/pyproject.toml +1 -1
  23. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/cli.py +143 -30
  24. fdl_cli-0.30.0/src/fdl/config.py +70 -0
  25. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/layout.py +3 -1
  26. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/repo.py +234 -45
  27. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_cli.py +122 -2
  28. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_http.py +9 -0
  29. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_objects.py +3 -1
  30. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_repo.py +57 -7
  31. fdl_cli-0.30.0/tests/test_retention_cases.py +45 -0
  32. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/uv.lock +1 -1
  33. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/.github/workflows/docs.yml +0 -0
  34. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/.github/workflows/publish.yml +0 -0
  35. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/.github/workflows/release.yml +0 -0
  36. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/.github/workflows/test.yml +0 -0
  37. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/.gitignore +0 -0
  38. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/.node-version +0 -0
  39. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/.python-version +0 -0
  40. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/CLAUDE.md +0 -0
  41. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/CONTRIBUTING.md +0 -0
  42. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/LICENSE +0 -0
  43. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/README.md +0 -0
  44. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/SECURITY.md +0 -0
  45. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/blume.config.ts +0 -0
  46. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/cases/collection.json +0 -0
  47. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/cases/data-dir.json +0 -0
  48. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/concepts/meta.ts +0 -0
  49. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/concepts/repositories.md +0 -0
  50. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/concepts/versions-and-refs.md +0 -0
  51. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/concepts/working-metadata.md +0 -0
  52. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/guides/building-a-host.md +0 -0
  53. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/guides/meta.ts +0 -0
  54. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/guides/public-and-private.md +0 -0
  55. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/guides/reading-without-duckdb.md +0 -0
  56. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/guides/serving-over-http.md +0 -0
  57. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/guides/stores.md +0 -0
  58. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/index.md +0 -0
  59. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/internals/ducklake-formats.md +0 -0
  60. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/internals/from-write-to-read.md +0 -0
  61. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/internals/meta.ts +0 -0
  62. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/concepts/meta.ts +0 -0
  63. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/concepts/repositories.md +0 -0
  64. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/concepts/versions-and-refs.md +0 -0
  65. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/concepts/working-metadata.md +0 -0
  66. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/guides/building-a-host.md +0 -0
  67. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/guides/meta.ts +0 -0
  68. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/guides/public-and-private.md +0 -0
  69. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/guides/reading-without-duckdb.md +0 -0
  70. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/guides/serving-over-http.md +0 -0
  71. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/guides/stores.md +0 -0
  72. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/index.md +0 -0
  73. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/internals/ducklake-formats.md +0 -0
  74. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/internals/from-write-to-read.md +0 -0
  75. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/internals/meta.ts +0 -0
  76. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/reference/meta.ts +0 -0
  77. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/collection-cases.md +0 -0
  78. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/http.md +0 -0
  79. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/index.md +0 -0
  80. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/layout.md +0 -0
  81. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/reading.md +0 -0
  82. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/refs.md +0 -0
  83. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/spec/writing.md +0 -0
  84. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/ja/stability.md +0 -0
  85. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/reference/meta.ts +0 -0
  86. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/collection-cases.md +0 -0
  87. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/http.md +0 -0
  88. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/index.md +0 -0
  89. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/layout.md +0 -0
  90. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/reading.md +0 -0
  91. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/refs.md +0 -0
  92. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/spec/writing.md +0 -0
  93. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/docs/stability.md +0 -0
  94. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/package-lock.json +0 -0
  95. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/package.json +0 -0
  96. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/public/CNAME +0 -0
  97. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/__init__.py +0 -0
  98. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/catalog.py +0 -0
  99. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/dataset.py +0 -0
  100. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/diff.py +0 -0
  101. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/lineage.py +0 -0
  102. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/merge.py +0 -0
  103. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/objects.py +0 -0
  104. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/profiles.py +0 -0
  105. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/py.typed +0 -0
  106. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/refs.py +0 -0
  107. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/store.py +0 -0
  108. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/stores.py +0 -0
  109. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/src/fdl/version.py +0 -0
  110. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/http_repo.py +0 -0
  111. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_collection_cases.py +0 -0
  112. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_data_dir_cases.py +0 -0
  113. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_dataset.py +0 -0
  114. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_merge.py +0 -0
  115. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_profiles.py +0 -0
  116. {fdl_cli-0.28.0 → fdl_cli-0.30.0}/tests/test_stores.py +0 -0
@@ -1,6 +1,91 @@
1
1
  # CHANGELOG
2
2
 
3
3
 
4
+ ## v0.30.0 (2026-11-15)
5
+
6
+ ### Bug Fixes
7
+
8
+ - Reject an --objects file that names no objects and read each version once
9
+ ([#69](https://github.com/queria-io/fdl/pull/69),
10
+ [`14e91da`](https://github.com/queria-io/fdl/commit/14e91da3a022d7afdb113aa9edb3bc884386fc54))
11
+
12
+ ### Features
13
+
14
+ - Keep merge bases with main and count retention on each branch
15
+ ([#67](https://github.com/queria-io/fdl/pull/67),
16
+ [`054228d`](https://github.com/queria-io/fdl/commit/054228dc43319c64e2b73998af656089d9297424))
17
+
18
+ * feat!: keep merge bases with main and count retention on each branch
19
+
20
+ fdl expire now decides for every live version at once, as the spec's new "Choosing the versions to
21
+ take out" says: it keeps the versions refs point at, their merge bases with main, the newest
22
+ --keep on each branch's first-parent line, and those made since --since or within --grace. Other
23
+ versions, such as the parents a merge brought in other than its first and the heads of deleted
24
+ request refs, are taken out. cases/retention.json holds the cases every implementation agrees on.
25
+
26
+ BREAKING CHANGE: fdl expire drops --ref and takes --grace (default 7d). repo.prune takes no newest
27
+ version and takes grace.
28
+
29
+ * fix: read each version once when choosing what to expire, and fix the retention cases example
30
+
31
+ - Name the objects a withdrawal deleted in expired.json
32
+ ([#68](https://github.com/queria-io/fdl/pull/68),
33
+ [`584e515`](https://github.com/queria-io/fdl/commit/584e5153389030d8e7a3d6ead7d69738ff46ec8f))
34
+
35
+ * feat: name the objects a withdrawal deleted in expired.json
36
+
37
+ Withdrawal now records the deleted data files (from data_dir) and assets (by sha256) as `deleted` in
38
+ each withdrawn version's expired.json. Mirrors delete exactly those, and hosts refuse to place
39
+ them again, so an old copy cannot bring withdrawn data back. Running a withdrawal again keeps the
40
+ names the first run wrote.
41
+
42
+ * feat: apply another repository's withdrawal by the objects it names
43
+
44
+ fdl withdraw --objects takes an expired.json (or its deleted) from the repository a mirror or fork
45
+ was copied from: every live version that reaches a named object is withdrawn too, and named
46
+ objects still there are deleted. --json prints the plan, listing refs that block it instead of
47
+ failing, for a host that moves them first.
48
+
49
+ * fix: read the data files of an s3:// repository with the AWS_* keys
50
+
51
+ withdraw and gc open each version's metadata to find the assets its rows reach. Over S3 DuckDB had
52
+ no secret for the data files, so they could not be read; the same secret fdl clone makes is now
53
+ used.
54
+
55
+ - Take the author from fdl config or FDL_AUTHOR_NAME when --author is left out
56
+ ([#66](https://github.com/queria-io/fdl/pull/66),
57
+ [`37da487`](https://github.com/queria-io/fdl/commit/37da487e4a156263091d4f1022475d386d19694f))
58
+
59
+ * feat: take the author from fdl config or FDL_AUTHOR_NAME when --author is left out
60
+
61
+ fdl config author.name and author.email keep who makes the versions in ~/.config/fdl/config.json.
62
+ FDL_AUTHOR_NAME and FDL_AUTHOR_EMAIL override them, and --author overrides both.
63
+
64
+ * fix: take the author's name and email from one place, and report a broken config.json
65
+
66
+
67
+ ## v0.29.0 (2026-11-15)
68
+
69
+ ### Features
70
+
71
+ - Record who takes a version out in expired.json, and keep version.json on withdrawal
72
+ ([#65](https://github.com/queria-io/fdl/pull/65),
73
+ [`1d3159b`](https://github.com/queria-io/fdl/commit/1d3159b4a50d309424b4b25a756477f7c225934b))
74
+
75
+ A withdrawal no longer deletes version.json: it rewrites the fields that hold the data, so every
76
+ repository holds its history back to the first version. expire and withdraw take --by, recorded in
77
+ expired.json.
78
+
79
+ - Write the version's dataset.json, README and docs/ on clone
80
+ ([#64](https://github.com/queria-io/fdl/pull/64),
81
+ [`1f37b04`](https://github.com/queria-io/fdl/commit/1f37b047866e662ff967e4adda561ed5ba5018e1))
82
+
83
+ A clone made only the working metadata, so whoever cloned a dataset had to write its description
84
+ again before they could commit. Clone now writes the version's dataset.json (without what commit
85
+ fills in) and the files of its tree.json into the current folder, unless a description is already
86
+ there.
87
+
88
+
4
89
  ## v0.28.0 (2026-11-15)
5
90
 
6
91
  ### Bug Fixes
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: fdl-cli
3
- Version: 0.28.0
3
+ Version: 0.30.0
4
4
  Summary: Versions of a DuckLake catalog on object storage, kept the way Git keeps commits
5
5
  Project-URL: Homepage, https://fdl.queria.io/
6
6
  Project-URL: Documentation, https://fdl.queria.io/
@@ -0,0 +1,325 @@
1
+ {
2
+ "now": "2026-11-12T00:00:00Z",
3
+ "grace_seconds": 86400,
4
+ "record": {
5
+ "fdl": "0.1",
6
+ "seq": 1,
7
+ "author": {
8
+ "name": "example"
9
+ },
10
+ "message": "",
11
+ "metadata": {
12
+ "path": "metadata.db",
13
+ "storage": "sqlite-3",
14
+ "bytes": 0,
15
+ "sha256": "0000000000000000000000000000000000000000000000000000000000000000"
16
+ },
17
+ "ducklake": {
18
+ "format": "1.0",
19
+ "snapshot_id": 1,
20
+ "snapshots": [1]
21
+ }
22
+ },
23
+ "cases": [
24
+ {
25
+ "name": "keeps the newest on main and what a ref points at",
26
+ "keep": 2,
27
+ "since": null,
28
+ "versions": [
29
+ {
30
+ "id": "019a0000-0000-7000-8000-000000000001",
31
+ "parents": [],
32
+ "created_at": "2026-11-01T00:00:00Z"
33
+ },
34
+ {
35
+ "id": "019a0000-0000-7000-8000-000000000002",
36
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
37
+ "created_at": "2026-11-02T00:00:00Z"
38
+ },
39
+ {
40
+ "id": "019a0000-0000-7000-8000-000000000003",
41
+ "parents": ["019a0000-0000-7000-8000-000000000002"],
42
+ "created_at": "2026-11-03T00:00:00Z"
43
+ },
44
+ {
45
+ "id": "019a0000-0000-7000-8000-000000000004",
46
+ "parents": ["019a0000-0000-7000-8000-000000000003"],
47
+ "created_at": "2026-11-04T00:00:00Z"
48
+ }
49
+ ],
50
+ "expired": [],
51
+ "refs": {
52
+ "refs/heads/main": "019a0000-0000-7000-8000-000000000004",
53
+ "refs/tags/first": "019a0000-0000-7000-8000-000000000001"
54
+ },
55
+ "take_out": ["019a0000-0000-7000-8000-000000000002"]
56
+ },
57
+ {
58
+ "name": "keeps the newest on each branch and its merge base with main",
59
+ "keep": 1,
60
+ "since": null,
61
+ "versions": [
62
+ {
63
+ "id": "019a0000-0000-7000-8000-000000000001",
64
+ "parents": [],
65
+ "created_at": "2026-11-01T00:00:00Z"
66
+ },
67
+ {
68
+ "id": "019a0000-0000-7000-8000-000000000002",
69
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
70
+ "created_at": "2026-11-02T00:00:00Z"
71
+ },
72
+ {
73
+ "id": "019a0000-0000-7000-8000-000000000003",
74
+ "parents": ["019a0000-0000-7000-8000-000000000002"],
75
+ "created_at": "2026-11-03T00:00:00Z"
76
+ },
77
+ {
78
+ "id": "019a0000-0000-7000-8000-000000000011",
79
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
80
+ "created_at": "2026-11-02T12:00:00Z"
81
+ },
82
+ {
83
+ "id": "019a0000-0000-7000-8000-000000000012",
84
+ "parents": ["019a0000-0000-7000-8000-000000000011"],
85
+ "created_at": "2026-11-03T12:00:00Z"
86
+ }
87
+ ],
88
+ "expired": [],
89
+ "refs": {
90
+ "refs/heads/main": "019a0000-0000-7000-8000-000000000003",
91
+ "refs/heads/fix": "019a0000-0000-7000-8000-000000000012"
92
+ },
93
+ "take_out": ["019a0000-0000-7000-8000-000000000002", "019a0000-0000-7000-8000-000000000011"]
94
+ },
95
+ {
96
+ "name": "takes out the parents merges brought once they fall behind their branch",
97
+ "keep": 2,
98
+ "since": null,
99
+ "versions": [
100
+ {
101
+ "id": "019a0000-0000-7000-8000-000000000001",
102
+ "parents": [],
103
+ "created_at": "2026-11-01T00:00:00Z"
104
+ },
105
+ {
106
+ "id": "019a0000-0000-7000-8000-000000000011",
107
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
108
+ "created_at": "2026-11-02T00:00:00Z"
109
+ },
110
+ {
111
+ "id": "019a0000-0000-7000-8000-000000000021",
112
+ "parents": [
113
+ "019a0000-0000-7000-8000-000000000001",
114
+ "019a0000-0000-7000-8000-000000000011"
115
+ ],
116
+ "created_at": "2026-11-02T01:00:00Z"
117
+ },
118
+ {
119
+ "id": "019a0000-0000-7000-8000-000000000012",
120
+ "parents": ["019a0000-0000-7000-8000-000000000011"],
121
+ "created_at": "2026-11-03T00:00:00Z"
122
+ },
123
+ {
124
+ "id": "019a0000-0000-7000-8000-000000000022",
125
+ "parents": [
126
+ "019a0000-0000-7000-8000-000000000021",
127
+ "019a0000-0000-7000-8000-000000000012"
128
+ ],
129
+ "created_at": "2026-11-03T01:00:00Z"
130
+ },
131
+ {
132
+ "id": "019a0000-0000-7000-8000-000000000013",
133
+ "parents": ["019a0000-0000-7000-8000-000000000012"],
134
+ "created_at": "2026-11-04T00:00:00Z"
135
+ },
136
+ {
137
+ "id": "019a0000-0000-7000-8000-000000000023",
138
+ "parents": [
139
+ "019a0000-0000-7000-8000-000000000022",
140
+ "019a0000-0000-7000-8000-000000000013"
141
+ ],
142
+ "created_at": "2026-11-04T01:00:00Z"
143
+ }
144
+ ],
145
+ "expired": [],
146
+ "refs": {
147
+ "refs/heads/main": "019a0000-0000-7000-8000-000000000023",
148
+ "refs/heads/apply": "019a0000-0000-7000-8000-000000000013"
149
+ },
150
+ "take_out": [
151
+ "019a0000-0000-7000-8000-000000000001",
152
+ "019a0000-0000-7000-8000-000000000011",
153
+ "019a0000-0000-7000-8000-000000000021"
154
+ ]
155
+ },
156
+ {
157
+ "name": "keeps the merge base of a request with main",
158
+ "keep": 1,
159
+ "since": null,
160
+ "versions": [
161
+ {
162
+ "id": "019a0000-0000-7000-8000-000000000001",
163
+ "parents": [],
164
+ "created_at": "2026-11-01T00:00:00Z"
165
+ },
166
+ {
167
+ "id": "019a0000-0000-7000-8000-000000000002",
168
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
169
+ "created_at": "2026-11-02T00:00:00Z"
170
+ },
171
+ {
172
+ "id": "019a0000-0000-7000-8000-000000000003",
173
+ "parents": ["019a0000-0000-7000-8000-000000000002"],
174
+ "created_at": "2026-11-03T00:00:00Z"
175
+ },
176
+ {
177
+ "id": "019a0000-0000-7000-8000-000000000004",
178
+ "parents": ["019a0000-0000-7000-8000-000000000003"],
179
+ "created_at": "2026-11-04T00:00:00Z"
180
+ },
181
+ {
182
+ "id": "019a0000-0000-7000-8000-000000000031",
183
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
184
+ "created_at": "2026-11-02T06:00:00Z"
185
+ }
186
+ ],
187
+ "expired": [],
188
+ "refs": {
189
+ "refs/heads/main": "019a0000-0000-7000-8000-000000000004",
190
+ "refs/requests/1": "019a0000-0000-7000-8000-000000000031"
191
+ },
192
+ "take_out": ["019a0000-0000-7000-8000-000000000002", "019a0000-0000-7000-8000-000000000003"]
193
+ },
194
+ {
195
+ "name": "takes out the head of a request once its ref is deleted",
196
+ "keep": 1,
197
+ "since": null,
198
+ "versions": [
199
+ {
200
+ "id": "019a0000-0000-7000-8000-000000000001",
201
+ "parents": [],
202
+ "created_at": "2026-11-01T00:00:00Z"
203
+ },
204
+ {
205
+ "id": "019a0000-0000-7000-8000-000000000002",
206
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
207
+ "created_at": "2026-11-02T00:00:00Z"
208
+ },
209
+ {
210
+ "id": "019a0000-0000-7000-8000-000000000031",
211
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
212
+ "created_at": "2026-11-02T06:00:00Z"
213
+ }
214
+ ],
215
+ "expired": [],
216
+ "refs": {
217
+ "refs/heads/main": "019a0000-0000-7000-8000-000000000002"
218
+ },
219
+ "take_out": ["019a0000-0000-7000-8000-000000000001", "019a0000-0000-7000-8000-000000000031"]
220
+ },
221
+ {
222
+ "name": "keeps a version made within the grace period that no ref points at yet",
223
+ "keep": 1,
224
+ "since": null,
225
+ "versions": [
226
+ {
227
+ "id": "019a0000-0000-7000-8000-000000000001",
228
+ "parents": [],
229
+ "created_at": "2026-11-01T00:00:00Z"
230
+ },
231
+ {
232
+ "id": "019a0000-0000-7000-8000-000000000002",
233
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
234
+ "created_at": "2026-11-02T00:00:00Z"
235
+ },
236
+ {
237
+ "id": "019a0000-0000-7000-8000-000000000003",
238
+ "parents": ["019a0000-0000-7000-8000-000000000002"],
239
+ "created_at": "2026-11-11T12:00:00Z"
240
+ }
241
+ ],
242
+ "expired": [],
243
+ "refs": {
244
+ "refs/heads/main": "019a0000-0000-7000-8000-000000000002"
245
+ },
246
+ "take_out": ["019a0000-0000-7000-8000-000000000001"]
247
+ },
248
+ {
249
+ "name": "keeps what was made since",
250
+ "keep": 1,
251
+ "since": "2026-11-02T00:00:00Z",
252
+ "versions": [
253
+ {
254
+ "id": "019a0000-0000-7000-8000-000000000001",
255
+ "parents": [],
256
+ "created_at": "2026-11-01T00:00:00Z"
257
+ },
258
+ {
259
+ "id": "019a0000-0000-7000-8000-000000000002",
260
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
261
+ "created_at": "2026-11-02T00:00:00Z"
262
+ },
263
+ {
264
+ "id": "019a0000-0000-7000-8000-000000000003",
265
+ "parents": ["019a0000-0000-7000-8000-000000000002"],
266
+ "created_at": "2026-11-03T00:00:00Z"
267
+ }
268
+ ],
269
+ "expired": [],
270
+ "refs": {
271
+ "refs/heads/main": "019a0000-0000-7000-8000-000000000003"
272
+ },
273
+ "take_out": ["019a0000-0000-7000-8000-000000000001"]
274
+ },
275
+ {
276
+ "name": "leaves versions already past retention alone",
277
+ "keep": 1,
278
+ "since": null,
279
+ "versions": [
280
+ {
281
+ "id": "019a0000-0000-7000-8000-000000000001",
282
+ "parents": [],
283
+ "created_at": "2026-11-01T00:00:00Z"
284
+ },
285
+ {
286
+ "id": "019a0000-0000-7000-8000-000000000002",
287
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
288
+ "created_at": "2026-11-02T00:00:00Z"
289
+ },
290
+ {
291
+ "id": "019a0000-0000-7000-8000-000000000003",
292
+ "parents": ["019a0000-0000-7000-8000-000000000002"],
293
+ "created_at": "2026-11-03T00:00:00Z"
294
+ }
295
+ ],
296
+ "expired": ["019a0000-0000-7000-8000-000000000001"],
297
+ "refs": {
298
+ "refs/heads/main": "019a0000-0000-7000-8000-000000000003"
299
+ },
300
+ "take_out": ["019a0000-0000-7000-8000-000000000002"]
301
+ },
302
+ {
303
+ "name": "takes nothing out without refs/heads/main",
304
+ "keep": 1,
305
+ "since": null,
306
+ "versions": [
307
+ {
308
+ "id": "019a0000-0000-7000-8000-000000000001",
309
+ "parents": [],
310
+ "created_at": "2026-11-01T00:00:00Z"
311
+ },
312
+ {
313
+ "id": "019a0000-0000-7000-8000-000000000002",
314
+ "parents": ["019a0000-0000-7000-8000-000000000001"],
315
+ "created_at": "2026-11-02T00:00:00Z"
316
+ }
317
+ ],
318
+ "expired": [],
319
+ "refs": {
320
+ "refs/heads/draft": "019a0000-0000-7000-8000-000000000002"
321
+ },
322
+ "take_out": []
323
+ }
324
+ ]
325
+ }
@@ -140,6 +140,8 @@ fdl commit work/lake.sqlite -m "Add 2026" --author alice
140
140
  fdl push work/lake.sqlite
141
141
  ```
142
142
 
143
+ The current folder already holds `dataset.json`, so the clone leaves it as it is. In an empty folder, the clone also writes the version's `dataset.json`, `README.md` and `docs/` there, so whoever clones the repository can change the description as well as the data.
144
+
143
145
  The new version lists the first as its parent. Both metadata files name the first Parquet file; only the second names the new one.
144
146
 
145
147
  If someone else pushed in between, the push is refused, because the new version would not be built on what `main` holds now. Clone again and redo the change. [Versions and refs](/concepts/versions-and-refs) explains why.
@@ -50,4 +50,4 @@ Anyone can write a `version.json`, so a checksum shows the copy matches the reco
50
50
 
51
51
  When the origin takes a version out of retention, the mirror sees `expired.json` appear and the metadata disappear on the next copy. Copy `expired.json` and delete the metadata files the origin deleted. A mirror that keeps them serves versions its origin no longer does.
52
52
 
53
- An `expired.json` with `"reason": "withdrawn"` means the origin removed data that must not be published. Delete the metadata files, the data files and the assets the origin deleted, without waiting.
53
+ An `expired.json` with `"reason": "withdrawn"` means the origin removed data that must not be published. Delete the metadata files, and the data files and assets named in its `deleted`, without waiting. Do not copy those objects again from anywhere. `fdl withdraw <mirror> --objects expired.json --yes` does this.
@@ -109,7 +109,7 @@ A tag is created with `If-None-Match: *` and never moved. Readers who attach `re
109
109
 
110
110
  ## Taking versions out of retention
111
111
 
112
- Metadata files are small, but a dataset that is rebuilt every day keeps every Parquet file any version names. `fdl expire --keep 30` takes the versions behind the newest 30 out of retention. Each goes through three steps:
112
+ Metadata files are small, but a dataset that is rebuilt every day keeps every Parquet file any version names. `fdl expire --keep 30` takes out of retention the versions behind the newest 30 on each branch, keeping those refs point at and their merge bases with main. Each goes through three steps:
113
113
 
114
114
  1. Put `versions/<ID>/expired.json`
115
115
  2. Delete `versions/<ID>/metadata.db` and any `metadata/`
@@ -140,6 +140,8 @@ fdl commit work/lake.sqlite -m "Add 2026" --author alice
140
140
  fdl push work/lake.sqlite
141
141
  ```
142
142
 
143
+ 今のフォルダには `dataset.json` があるので、クローンはそれをそのままにします。空のフォルダでは、バージョンの `dataset.json`・`README.md`・`docs/` もそこに書き出すので、リポジトリをクローンした人はデータだけでなく説明も変えられます。
144
+
143
145
  新しいバージョンは、最初のバージョンを親として記録します。最初の Parquet ファイルは両方のメタデータが参照し、新しいファイルは 2 つめのメタデータだけが参照します。
144
146
 
145
147
  途中でほかの人が push していたら、この push は断られます。新しいバージョンが、いまの `main` の上に積まれていないためです。クローンし直して、変更をやり直してください。理由は[バージョンと ref](/ja/concepts/versions-and-refs) で説明しています。
@@ -50,4 +50,4 @@ ATTACH 'ducklake:https://mirror.example.org/towns/versions/019a3c4e-…/metadata
50
50
 
51
51
  元がバージョンの保持期間を終わらせると、ミラーは次に写すときに、`expired.json` が増え、メタデータが消えたことに気づきます。`expired.json` を写し、元が消したメタデータを消してください。残しておくと、元がもう出していないバージョンをミラーが出し続けます。
52
52
 
53
- `"reason": "withdrawn"` の `expired.json` は、公開してはいけないデータを元が取り下げたことを意味します。元が消したメタデータ・データファイル・アセットを、待たずに消してください。
53
+ `"reason": "withdrawn"` の `expired.json` は、公開してはいけないデータを元が取り下げたことを意味します。メタデータと、`deleted` にあるデータファイル・アセットを、待たずに消してください。それらのオブジェクトをどこからも写し直さないでください。`fdl withdraw <mirror> --objects expired.json --yes` がこれを行います。
@@ -109,7 +109,7 @@ data/main/towns/ducklake-019a3b….parquet 2 つめだけが参照
109
109
 
110
110
  ## 保持期間を過ぎたバージョン
111
111
 
112
- メタデータは小さくても、毎日作り直すデータセットは、どれかのバージョンが参照する Parquet ファイルをすべて持ち続けます。`fdl expire --keep 30` は、新しい 30 個より古いバージョンの保持期間を終わらせます。それぞれ次の 3 段階を踏みます。
112
+ メタデータは小さくても、毎日作り直すデータセットは、どれかのバージョンが参照する Parquet ファイルをすべて持ち続けます。`fdl expire --keep 30` は、各ブランチの新しい 30 個より古いバージョンの保持期間を終わらせます。ref が指すバージョンと、その main との共通祖先は残します。それぞれ次の 3 段階を踏みます。
113
113
 
114
114
  1. `versions/<ID>/expired.json` を置く
115
115
  2. `versions/<ID>/metadata.db` と `metadata/` を消す
@@ -43,12 +43,24 @@ HTTP のリポジトリでは、新しいデータファイルは `<working.sqli
43
43
 
44
44
  `--storage` を付けると、作業メタデータはリポジトリのストレージで直接データファイルを読み書きします。`--storage` にはそのストレージでのリポジトリの根を渡します。新しいファイルはその `data_dir` の下に直接書かれるので、push でアップロードするものはありません。鍵は `AWS_*` の環境変数(R2 などの S3 互換ストレージは `AWS_ENDPOINT_URL`)か、自分で作った DuckDB の secret から取ります。作業メタデータに書くビルドにも同じ鍵が要ります。
45
45
 
46
- バージョンの保持期間が過ぎているとき、メタデータの sha256 が `version.json` の記録と違うとき、メタデータがデータフォルダの外のデータファイルを指しているときは断られます。
46
+ 今のフォルダに `dataset.json` も `dataset.yml` も無いときは、`fdl commit` が読むファイルもそこに書き出します。バージョンの `dataset.json` からコミットがカタログから埋める値(行数、列の型、NULL の可否)を除いたものと、`tree.json` が挙げるファイル(`README.md` や `docs/` など)です。これらを編集してコミットすると説明を変えられます。フォルダに既に説明があるときはそのままにし、何も書きません。
47
+
48
+ バージョンの保持期間が過ぎているとき、メタデータの sha256 が `version.json` の記録と違うとき、メタデータがデータフォルダの外のデータファイルを指しているとき、書き出すファイルが今のフォルダに既にあるときは断られます。
49
+
50
+ ## fdl config
51
+
52
+ ```bash
53
+ fdl config author.name "Alice"
54
+ fdl config author.email alice@example.com
55
+ fdl config author.name
56
+ ```
57
+
58
+ コミットするバージョンの作者を設定します。設定はリポジトリとは別に `~/.config/fdl/config.json`(`$XDG_CONFIG_HOME` があればその下)に保存します。値を省くと、設定した値を表示します。`fdl commit`・`fdl revert`・`fdl merge` は、作者を `--author`、環境変数 `FDL_AUTHOR_NAME` と `FDL_AUTHOR_EMAIL`、この設定の順に探し、どれにも名前が無ければ断ります。
47
59
 
48
60
  ## fdl commit
49
61
 
50
62
  ```bash
51
- fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.json] [--allow-empty] [--assets files/]
63
+ fdl commit <working.sqlite> -m "What changed" [--author alice] [--dataset dataset.json] [--allow-empty] [--assets files/]
52
64
  ```
53
65
 
54
66
  作業メタデータを、クローンした(または最後に push した)バージョンを親とする新しいバージョンに固め、`fdl push` で送るまで `<working.sqlite>.pending/` に置きます。リポジトリは何も変わりません。新しいバージョン ID と `seq` を表示します。push する前にもう一度コミットすると、まだ push していないバージョンを置き換えます。
@@ -173,7 +185,7 @@ fdl branch <remote> <name> --delete
173
185
  ## fdl revert
174
186
 
175
187
  ```bash
176
- fdl revert <version> <working.sqlite> --author <name> [-m <message>]
188
+ fdl revert <version> <working.sqlite> [--author <name>] [-m <message>]
177
189
  fdl push <working.sqlite>
178
190
  ```
179
191
 
@@ -184,7 +196,7 @@ fdl push <working.sqlite>
184
196
  ## fdl merge
185
197
 
186
198
  ```bash
187
- fdl merge <theirs> <working.sqlite> --author <name> [-m <message>]
199
+ fdl merge <theirs> <working.sqlite> [--author <name>] [-m <message>]
188
200
  fdl push <working.sqlite>
189
201
  ```
190
202
 
@@ -211,15 +223,19 @@ fdl push <working.sqlite>
211
223
  ## fdl withdraw
212
224
 
213
225
  ```bash
214
- fdl withdraw <remote> <version>... [--yes]
226
+ fdl withdraw <remote> [<version>...] [--objects <file>] [--json] [--yes] [--by <name>]
215
227
  ```
216
228
 
217
- 間違って公開した個人データなど、公開してはいけないデータを持つバージョンを取り下げます([取り下げ](/ja/spec/data-files#取り下げ))。先にそのデータを除いたバージョンをコミットし、該当するバージョンを指すブランチが無い状態にします。そのうえでこのコマンドが、該当するバージョンを指すタグ、そのバージョンが参照し残すバージョンが参照しないデータファイルとアセット、メタデータを消し、`"reason": "withdrawn"` の `expired.json` を置きます。`version.json` は残します。保持期間を過ぎたバージョンを含めると、そのメタデータはもう無いので、有効なバージョンのどれも参照しないデータファイルとアセットを、猶予期間を待たずにすべて消します。
229
+ 間違って公開した個人データなど、公開してはいけないデータを持つバージョンを取り下げます([取り下げ](/ja/spec/data-files#取り下げ))。先にそのデータを除いたバージョンをコミットし、該当するバージョンを指すブランチが無い状態にします。そのうえでこのコマンドが、該当するバージョンを指すタグ、そのバージョンが参照し残すバージョンが参照しないデータファイルとアセット、メタデータを消し、`"reason": "withdrawn"` と消したオブジェクトの名前(`deleted`)を持つ `expired.json` を置きます。`version.json` は残します。保持期間を過ぎたバージョンを含めると、そのメタデータはもう無いので、有効なバージョンのどれも参照しないデータファイルとアセットを、猶予期間を待たずにすべて消します。
218
230
 
219
231
  バージョンが参照するアセットは、`tree.json` に載っているものと、アセット列が持つ sha256 です。
220
232
 
221
233
  `--yes` を付けないと、消すものを表示するだけです。残すバージョンが参照しているファイルは残すものとして表示します。それがそのデータを持つなら、そのバージョンも取り下げます。ブランチかリクエストが該当するバージョンを指しているあいだは断られます。
222
234
 
235
+ `--objects` は、別のリポジトリで行った取り下げを、その写し(ミラーやフォーク)に適用します。ファイルはそのリポジトリの `expired.json` か、その `deleted` だけです。名前のあるオブジェクトを参照する有効なバージョンも、指定したバージョンと一緒に取り下げます。名前のあるオブジェクトは、どのバージョンも参照していなくても、残っていれば消します。
236
+
237
+ `--json` は計画を 1 つの JSON(`versions`・`tags`・`deleted`・`still_read`・`blocked`)で表示します。該当するバージョンを指すタグ以外の ref は、断る代わりに `blocked` に並べます。ホストがそれらを動かしてから `--yes` で実行するためです。
238
+
223
239
  ## fdl profile
224
240
 
225
241
  ```bash
@@ -231,10 +247,10 @@ fdl profile <remote> [--ref refs/heads/main]
231
247
  ## fdl expire
232
248
 
233
249
  ```bash
234
- fdl expire <remote> [--keep 1] [--since 2026-10-01T00:00:00Z] [--ref refs/heads/main]
250
+ fdl expire <remote> [--keep 1] [--since 2026-10-01T00:00:00Z] [--grace 7d] [--by <name>]
235
251
  ```
236
252
 
237
- ブランチの最初の親のつながりで、新しい `--keep` 個より古いバージョンの保持期間を終わらせます。`expired.json` を置き、メタデータを消します。`--since` 以降に作ったバージョンと、ref が指すバージョンは残します。データファイルは消しません。消すのは `fdl gc` です。
253
+ バージョンの保持期間を終わらせます。`expired.json` を置き、メタデータを消します。残すのは、各ブランチの最初の親のつながりで新しい `--keep` 個、ref が指すバージョン、その main との共通祖先、`--since` 以降または `--grace` のうちに作ったバージョンです。それ以外(マージが取り込んだ最初の親以外の親など)は保持期間を終わらせます([保持期間を終わらせるバージョンの選び方](/ja/spec/data-files#保持期間を終わらせるバージョンの選び方))。main にバージョンが無いうちは何も終わらせません。データファイルは消しません。消すのは `fdl gc` です。`--by` は保持期間を終わらせた人を `expired.json` に記録します。`fdl withdraw` の `--by` も同じです。
238
254
 
239
255
  ## fdl gc
240
256
 
@@ -99,10 +99,11 @@ ref が指すバージョンを、読み手がメタデータを開く前に行
99
99
 
100
100
  ```python
101
101
  repo.expire(store, version_id, *, reason="retention") -> None
102
- repo.prune(store, newest, *, keep=1, since=None, reason="retention") -> list[str]
102
+ repo.plan_retention(store, *, keep=1, since=None, grace=timedelta(days=7), now=None) -> list[str]
103
+ repo.prune(store, *, keep=1, since=None, grace=timedelta(days=7), reason="retention", by=None) -> list[str]
103
104
  ```
104
105
 
105
- バージョン 1 つの保持期間を終わらせるか、`newest` より古く保持期間から外れるバージョンをまとめて終わらせます。ref が指すバージョンは残します。
106
+ バージョン 1 つの保持期間を終わらせるか、`plan_retention` が選ぶバージョンをまとめて終わらせます([保持期間を終わらせるバージョンの選び方](/ja/spec/data-files#保持期間を終わらせるバージョンの選び方))。`plan_retention` は一覧を返すだけです。ref が指すバージョンは残します。
106
107
 
107
108
  ```python
108
109
  repo.tag(store, name, version_id) -> None
@@ -127,11 +128,11 @@ repo.update_refs_index(store) -> None
127
128
  ref を読み直して `refs.json` を書き直します。`push`・`tag`・`delete_tag` は ref を動かしたあとにこれを呼びます。`refs.json` を自分で書くホストが 403 で断ったときは、済んだものとして扱います。
128
129
 
129
130
  ```python
130
- repo.plan_withdrawal(store, version_ids) -> Withdrawal
131
+ repo.plan_withdrawal(store, version_ids, *, objects=None, refuse_refs=True) -> Withdrawal
131
132
  repo.withdraw(store, version_ids, *, plan=None) -> Withdrawal
132
133
  ```
133
134
 
134
- 公開してはいけないデータを持つバージョンを取り下げます。`plan_withdrawal` は何も変えずに、消すタグ、消すデータファイル、残すバージョンが読むので残すファイルを返します。`withdraw` はタグ、データファイル、メタデータの順に消します。ブランチかリクエストが該当するバージョンを指しているあいだは、どちらも `RepoError` を出します。
135
+ 公開してはいけないデータを持つバージョンを取り下げます。`plan_withdrawal` は何も変えずに、消すタグ、消すデータファイル、残すバージョンが読むので残すファイルを返します。`withdraw` はタグ、データファイル、メタデータの順に消します。ブランチかリクエストが該当するバージョンを指しているあいだは、どちらも `RepoError` を出します。`refuse_refs=False` のときは、`plan_withdrawal` はそれらを `blocked` に並べ、`withdraw` が `RepoError` を出します。`objects`(`expired.json` の `deleted` と同じ `{"data": [...], "assets": [...]}`)は、写し元のリポジトリで行った取り下げを適用します。それらを参照する有効なバージョンも該当するバージョンになります。
135
136
 
136
137
  ## fdl.diff
137
138