fdl-cli 0.30.0__tar.gz → 0.31.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.30.0 → fdl_cli-0.31.0}/CHANGELOG.md +18 -0
  2. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/PKG-INFO +1 -1
  3. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/reference/cli.md +4 -4
  4. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/data-files.md +5 -3
  5. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/reference/cli.md +4 -4
  6. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/data-files.md +5 -3
  7. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/pyproject.toml +1 -1
  8. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/cli.py +5 -3
  9. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/repo.py +17 -5
  10. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_repo.py +4 -2
  11. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/uv.lock +1 -1
  12. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/.github/workflows/docs.yml +0 -0
  13. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/.github/workflows/publish.yml +0 -0
  14. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/.github/workflows/release.yml +0 -0
  15. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/.github/workflows/test.yml +0 -0
  16. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/.gitignore +0 -0
  17. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/.node-version +0 -0
  18. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/.python-version +0 -0
  19. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/CLAUDE.md +0 -0
  20. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/CONTRIBUTING.md +0 -0
  21. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/LICENSE +0 -0
  22. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/README.md +0 -0
  23. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/SECURITY.md +0 -0
  24. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/blume.config.ts +0 -0
  25. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/cases/collection.json +0 -0
  26. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/cases/data-dir.json +0 -0
  27. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/cases/retention.json +0 -0
  28. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/concepts/meta.ts +0 -0
  29. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/concepts/repositories.md +0 -0
  30. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/concepts/versions-and-refs.md +0 -0
  31. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/concepts/working-metadata.md +0 -0
  32. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/getting-started.md +0 -0
  33. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/guides/building-a-host.md +0 -0
  34. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/guides/meta.ts +0 -0
  35. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/guides/mirrors.md +0 -0
  36. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/guides/public-and-private.md +0 -0
  37. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/guides/reading-without-duckdb.md +0 -0
  38. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/guides/serving-over-http.md +0 -0
  39. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/guides/stores.md +0 -0
  40. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/index.md +0 -0
  41. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/internals/ducklake-formats.md +0 -0
  42. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/internals/from-write-to-read.md +0 -0
  43. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/internals/inside-a-repository.md +0 -0
  44. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/internals/meta.ts +0 -0
  45. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/concepts/meta.ts +0 -0
  46. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/concepts/repositories.md +0 -0
  47. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/concepts/versions-and-refs.md +0 -0
  48. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/concepts/working-metadata.md +0 -0
  49. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/getting-started.md +0 -0
  50. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/guides/building-a-host.md +0 -0
  51. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/guides/meta.ts +0 -0
  52. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/guides/mirrors.md +0 -0
  53. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/guides/public-and-private.md +0 -0
  54. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/guides/reading-without-duckdb.md +0 -0
  55. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/guides/serving-over-http.md +0 -0
  56. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/guides/stores.md +0 -0
  57. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/index.md +0 -0
  58. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/internals/ducklake-formats.md +0 -0
  59. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/internals/from-write-to-read.md +0 -0
  60. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/internals/inside-a-repository.md +0 -0
  61. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/internals/meta.ts +0 -0
  62. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/reference/meta.ts +0 -0
  63. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/reference/python.md +0 -0
  64. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/collection-cases.md +0 -0
  65. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/http.md +0 -0
  66. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/index.md +0 -0
  67. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/layout.md +0 -0
  68. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/meta.ts +0 -0
  69. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/reading.md +0 -0
  70. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/refs.md +0 -0
  71. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/retention-cases.md +0 -0
  72. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/versions.md +0 -0
  73. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/spec/writing.md +0 -0
  74. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/ja/stability.md +0 -0
  75. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/reference/meta.ts +0 -0
  76. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/reference/python.md +0 -0
  77. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/collection-cases.md +0 -0
  78. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/http.md +0 -0
  79. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/index.md +0 -0
  80. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/layout.md +0 -0
  81. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/meta.ts +0 -0
  82. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/reading.md +0 -0
  83. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/refs.md +0 -0
  84. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/retention-cases.md +0 -0
  85. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/versions.md +0 -0
  86. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/spec/writing.md +0 -0
  87. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/docs/stability.md +0 -0
  88. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/package-lock.json +0 -0
  89. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/package.json +0 -0
  90. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/public/CNAME +0 -0
  91. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/__init__.py +0 -0
  92. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/catalog.py +0 -0
  93. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/config.py +0 -0
  94. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/dataset.py +0 -0
  95. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/diff.py +0 -0
  96. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/layout.py +0 -0
  97. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/lineage.py +0 -0
  98. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/merge.py +0 -0
  99. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/objects.py +0 -0
  100. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/profiles.py +0 -0
  101. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/py.typed +0 -0
  102. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/refs.py +0 -0
  103. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/store.py +0 -0
  104. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/stores.py +0 -0
  105. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/src/fdl/version.py +0 -0
  106. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/http_repo.py +0 -0
  107. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_cli.py +0 -0
  108. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_collection_cases.py +0 -0
  109. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_data_dir_cases.py +0 -0
  110. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_dataset.py +0 -0
  111. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_http.py +0 -0
  112. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_merge.py +0 -0
  113. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_objects.py +0 -0
  114. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_profiles.py +0 -0
  115. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_retention_cases.py +0 -0
  116. {fdl_cli-0.30.0 → fdl_cli-0.31.0}/tests/test_stores.py +0 -0
@@ -1,6 +1,24 @@
1
1
  # CHANGELOG
2
2
 
3
3
 
4
+ ## v0.31.0 (2026-11-15)
5
+
6
+ ### Documentation
7
+
8
+ - Keep withdrawn data out of expired.json by and message
9
+ ([#72](https://github.com/queria-io/fdl/pull/72),
10
+ [`e5147f9`](https://github.com/queria-io/fdl/commit/e5147f936f39356648a7b7e1afaaaafe56492b3b))
11
+
12
+ - Leave forks out of FDL and say by is free text ([#70](https://github.com/queria-io/fdl/pull/70),
13
+ [`2432a0a`](https://github.com/queria-io/fdl/commit/2432a0a18528b12f46530b3aea2e0988bcd04521))
14
+
15
+ ### Features
16
+
17
+ - Record why versions are taken out in expired.json message
18
+ ([#71](https://github.com/queria-io/fdl/pull/71),
19
+ [`d3616b7`](https://github.com/queria-io/fdl/commit/d3616b73a2a89ff8fbfac1dde51a424f5a5ac6f9))
20
+
21
+
4
22
  ## v0.30.0 (2026-11-15)
5
23
 
6
24
  ### Bug Fixes
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: fdl-cli
3
- Version: 0.30.0
3
+ Version: 0.31.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/
@@ -223,7 +223,7 @@ fdl push <working.sqlite>
223
223
  ## fdl withdraw
224
224
 
225
225
  ```bash
226
- fdl withdraw <remote> [<version>...] [--objects <file>] [--json] [--yes] [--by <name>]
226
+ fdl withdraw <remote> [<version>...] [--objects <file>] [--json] [--yes] [--by <name>] [-m <message>]
227
227
  ```
228
228
 
229
229
  間違って公開した個人データなど、公開してはいけないデータを持つバージョンを取り下げます([取り下げ](/ja/spec/data-files#取り下げ))。先にそのデータを除いたバージョンをコミットし、該当するバージョンを指すブランチが無い状態にします。そのうえでこのコマンドが、該当するバージョンを指すタグ、そのバージョンが参照し残すバージョンが参照しないデータファイルとアセット、メタデータを消し、`"reason": "withdrawn"` と消したオブジェクトの名前(`deleted`)を持つ `expired.json` を置きます。`version.json` は残します。保持期間を過ぎたバージョンを含めると、そのメタデータはもう無いので、有効なバージョンのどれも参照しないデータファイルとアセットを、猶予期間を待たずにすべて消します。
@@ -232,7 +232,7 @@ fdl withdraw <remote> [<version>...] [--objects <file>] [--json] [--yes] [--by <
232
232
 
233
233
  `--yes` を付けないと、消すものを表示するだけです。残すバージョンが参照しているファイルは残すものとして表示します。それがそのデータを持つなら、そのバージョンも取り下げます。ブランチかリクエストが該当するバージョンを指しているあいだは断られます。
234
234
 
235
- `--objects` は、別のリポジトリで行った取り下げを、その写し(ミラーやフォーク)に適用します。ファイルはそのリポジトリの `expired.json` か、その `deleted` だけです。名前のあるオブジェクトを参照する有効なバージョンも、指定したバージョンと一緒に取り下げます。名前のあるオブジェクトは、どのバージョンも参照していなくても、残っていれば消します。
235
+ `--objects` は、別のリポジトリで行った取り下げを、その写し(ミラーなど)に適用します。ファイルはそのリポジトリの `expired.json` か、その `deleted` だけです。名前のあるオブジェクトを参照する有効なバージョンも、指定したバージョンと一緒に取り下げます。名前のあるオブジェクトは、どのバージョンも参照していなくても、残っていれば消します。
236
236
 
237
237
  `--json` は計画を 1 つの JSON(`versions`・`tags`・`deleted`・`still_read`・`blocked`)で表示します。該当するバージョンを指すタグ以外の ref は、断る代わりに `blocked` に並べます。ホストがそれらを動かしてから `--yes` で実行するためです。
238
238
 
@@ -247,10 +247,10 @@ fdl profile <remote> [--ref refs/heads/main]
247
247
  ## fdl expire
248
248
 
249
249
  ```bash
250
- fdl expire <remote> [--keep 1] [--since 2026-10-01T00:00:00Z] [--grace 7d] [--by <name>]
250
+ fdl expire <remote> [--keep 1] [--since 2026-10-01T00:00:00Z] [--grace 7d] [--by <name>] [-m <message>]
251
251
  ```
252
252
 
253
- バージョンの保持期間を終わらせます。`expired.json` を置き、メタデータを消します。残すのは、各ブランチの最初の親のつながりで新しい `--keep` 個、ref が指すバージョン、その main との共通祖先、`--since` 以降または `--grace` のうちに作ったバージョンです。それ以外(マージが取り込んだ最初の親以外の親など)は保持期間を終わらせます([保持期間を終わらせるバージョンの選び方](/ja/spec/data-files#保持期間を終わらせるバージョンの選び方))。main にバージョンが無いうちは何も終わらせません。データファイルは消しません。消すのは `fdl gc` です。`--by` は保持期間を終わらせた人を `expired.json` に記録します。`fdl withdraw` の `--by` も同じです。
253
+ バージョンの保持期間を終わらせます。`expired.json` を置き、メタデータを消します。残すのは、各ブランチの最初の親のつながりで新しい `--keep` 個、ref が指すバージョン、その main との共通祖先、`--since` 以降または `--grace` のうちに作ったバージョンです。それ以外(マージが取り込んだ最初の親以外の親など)は保持期間を終わらせます([保持期間を終わらせるバージョンの選び方](/ja/spec/data-files#保持期間を終わらせるバージョンの選び方))。main にバージョンが無いうちは何も終わらせません。データファイルは消しません。消すのは `fdl gc` です。`--by` は保持期間を終わらせた人を、`--message` はその理由を `expired.json` に記録します。`fdl withdraw` の同じオプションも同じです。
254
254
 
255
255
  ## fdl gc
256
256
 
@@ -61,10 +61,11 @@ DuckLake 自身の片付け(`ducklake_cleanup_old_files`、`ducklake_expire_sn
61
61
  3. 猶予期間のあと、上の条件に合う共有オブジェクトを消す
62
62
 
63
63
  ```json expired.json
64
- { "expired_at": "2026-12-01T00:00:00Z", "reason": "retention", "by": "nightly retention" }
64
+ { "expired_at": "2026-12-01T00:00:00Z", "reason": "retention", "by": "nightly retention", "message": "Keep the newest 7 versions" }
65
65
  ```
66
66
 
67
- - `by` には、保持期間を終わらせた人や仕組み(定期実行のジョブなど)を書いてよい。これで履歴には、バージョンを作った人と同じく、そのデータを消した人も残る
67
+ - `by` には、保持期間を終わらせた人や仕組み(定期実行のジョブなど)を書いてよい。これで履歴には、バージョンを作った人と同じく、そのデータを消した人も残る。値は自由な文字列で、FDL は意味を持たせない。書くツールやホストが値を決める
68
+ - `message` には、その理由を自由な文で書いてよい。`version.json` の `message` が変更の内容を書くのと同じ。読み手が動作を決めるのは `reason` で、`message` は人が読むためのもの
68
69
  - `version.json` は残す。履歴にはそのバージョンがあったことと中身が残り、親のつながりも切れない
69
70
  - `expired.json` を見た読み手は、`reason` が何であれ、保持期間を過ぎたものとして扱い、メタデータを開かない
70
71
  - ref が指すバージョンの保持期間を終わらせてはいけない
@@ -107,7 +108,8 @@ DuckLake 自身の片付け(`ducklake_cleanup_old_files`、`ducklake_expire_sn
107
108
 
108
109
  - `deleted` は手順 3 で消した共有オブジェクトの名前です。データファイルは `data_dir` からのパス、アセットは sha256 で書きます。名前だけなので、データそのものは含みません。1 回の取り下げで該当するバージョンは、どれも同じ一覧を持ちます。途中で止まった取り下げをやり直すときは、すでに書かれた名前を残します。1 回目に消したオブジェクトは、やり直しでは見つからないことがあるためです
109
110
  - ホストは、どれかのバージョンの `deleted` にあるオブジェクトを置く push を断ります。リポジトリの間でバージョンを写す処理も、それらを写しません。そうしないと、手元の clone などの古い写しからデータが戻ります
110
- - ミラーやフォークなどリポジトリの写しは、`deleted` の名前で取り下げを適用します。写しの中でそれらを参照する有効なバージョンは、写しで作ったものも含めて、すべて該当するバージョンです。名前のあるオブジェクトは、どのバージョンも参照していなくても消します
111
+ - ミラーなどリポジトリの写しは、`deleted` の名前で取り下げを適用します。写しの中でそれらを参照する有効なバージョンは、写しで作ったものも含めて、すべて該当するバージョンです。名前のあるオブジェクトは、どのバージョンも参照していなくても消します
111
112
 
112
113
  - `version.json` は、保持期間のときと同じく残す。これで、どのリポジトリも最初のバージョンまでの履歴を持つ。記録そのもの(`author`・`message`・`inputs`)にそのデータがあれば、`expired.json` を置く前に記録を書き換えてデータを除く。`author` や `message` の該当する値は `withdrawn` に置き換え、`inputs` は該当する要素を除く。`id`・`seq`・`parents` などほかの項目はそのまま残す
114
+ - `expired.json` の `by` と `message` は取り下げのあとも読めるので、そこにもそのデータを書いてはいけない。理由は「誤って公開した個人データ」のように一般的な言葉で書く
113
115
  - ミラーは自分の写しを持っている。`"reason": "withdrawn"` の `expired.json` を写したミラーは、メタデータと `deleted` にある共有オブジェクトを消す。元のホストはこれを強制できないので、知っているミラーに伝える
@@ -223,7 +223,7 @@ Refused when the working metadata has changes not committed, when a version is c
223
223
  ## fdl withdraw
224
224
 
225
225
  ```bash
226
- fdl withdraw <remote> [<version>...] [--objects <file>] [--json] [--yes] [--by <name>]
226
+ fdl withdraw <remote> [<version>...] [--objects <file>] [--json] [--yes] [--by <name>] [-m <message>]
227
227
  ```
228
228
 
229
229
  Removes versions that hold data that must not be published, such as personal data published by mistake (see [Withdrawal](/spec/data-files#withdrawal)). First commit a version without the data, so that no branch points at an affected version. The command then deletes the tags that point at the versions, the data files and assets the versions reach that no kept version reaches, and their metadata files, and puts `expired.json` with `"reason": "withdrawn"` and the names of the deleted objects in `deleted`. `version.json` stays. When one of the versions is already past retention, its metadata is gone, so every data file and asset no live version reaches is deleted at once, without waiting for the grace period.
@@ -232,7 +232,7 @@ A version reaches the assets its `tree.json` lists and those its asset columns h
232
232
 
233
233
  Without `--yes` it only prints what it would delete. Files a kept version still reaches are listed as kept; if they hold the data, withdraw that version too. Refused while a branch or a request points at one of the versions.
234
234
 
235
- `--objects` applies a withdrawal made in another repository, in a copy of it such as a mirror or a fork. The file is that repository's `expired.json`, or just its `deleted`. Every live version that reaches one of the named objects is withdrawn too, with the versions given, and the named objects still there are deleted even where no version reaches them.
235
+ `--objects` applies a withdrawal made in another repository, in a copy of it such as a mirror. The file is that repository's `expired.json`, or just its `deleted`. Every live version that reaches one of the named objects is withdrawn too, with the versions given, and the named objects still there are deleted even where no version reaches them.
236
236
 
237
237
  `--json` prints the plan as one JSON object (`versions`, `tags`, `deleted`, `still_read`, `blocked`). Refs other than tags that point at the versions are listed in `blocked` instead of failing, for a host that moves them before running it with `--yes`.
238
238
 
@@ -247,10 +247,10 @@ Profiles the tables and views of the version the branch or tag holds that have n
247
247
  ## fdl expire
248
248
 
249
249
  ```bash
250
- fdl expire <remote> [--keep 1] [--since 2026-10-01T00:00:00Z] [--grace 7d] [--by <name>]
250
+ fdl expire <remote> [--keep 1] [--since 2026-10-01T00:00:00Z] [--grace 7d] [--by <name>] [-m <message>]
251
251
  ```
252
252
 
253
- Takes versions out of retention: puts `expired.json` and deletes their metadata files. Kept are the newest `--keep` on each branch's first-parent line, the versions refs point at, their merge bases with main, and the versions made at or after `--since` or within `--grace`. Other versions, such as the parents a merge brought in other than its first, are taken out ([Choosing the versions to take out](/spec/data-files#choosing-the-versions-to-take-out)). Nothing is taken out before main has a version. Data files are not deleted; `fdl gc` deletes them. `--by` records who takes the versions out in `expired.json`, as does `--by` of `fdl withdraw`.
253
+ Takes versions out of retention: puts `expired.json` and deletes their metadata files. Kept are the newest `--keep` on each branch's first-parent line, the versions refs point at, their merge bases with main, and the versions made at or after `--since` or within `--grace`. Other versions, such as the parents a merge brought in other than its first, are taken out ([Choosing the versions to take out](/spec/data-files#choosing-the-versions-to-take-out)). Nothing is taken out before main has a version. Data files are not deleted; `fdl gc` deletes them. `--by` records who takes the versions out in `expired.json`, and `--message` why, as do the same options of `fdl withdraw`.
254
254
 
255
255
  ## fdl gc
256
256
 
@@ -61,10 +61,11 @@ A version is taken out of retention in this order:
61
61
  3. After the grace period, delete the shared objects that meet the conditions above
62
62
 
63
63
  ```json expired.json
64
- { "expired_at": "2026-12-01T00:00:00Z", "reason": "retention", "by": "nightly retention" }
64
+ { "expired_at": "2026-12-01T00:00:00Z", "reason": "retention", "by": "nightly retention", "message": "Keep the newest 7 versions" }
65
65
  ```
66
66
 
67
- - `by` may say who or what took the version out: a person, or a process such as a scheduled job. With it, the history shows who removed each version's data, as it shows who made it
67
+ - `by` may say who or what took the version out: a person, or a process such as a scheduled job. With it, the history shows who removed each version's data, as it shows who made it. It is free text: FDL gives it no meaning, and the tool or host that writes it chooses the value
68
+ - `message` may say why, in free text, as `message` of `version.json` says what changed. `reason` is the value readers act on; `message` is for people
68
69
  - `version.json` stays, so the history still says the version was there and what it was, and the graph of parents stays whole
69
70
  - A reader that sees `expired.json` treats the version as past retention and does not open its metadata, whatever the `reason`
70
71
  - A version a ref points at must not be taken out
@@ -107,7 +108,8 @@ The shared objects go before the metadata files, so a withdrawal that stops half
107
108
 
108
109
  - `deleted` names the shared objects step 3 deleted: data files by their path under `data_dir`, assets by their sha256. Names only, so it holds none of the data. Every affected version of one withdrawal carries the same list. A withdrawal run again after stopping half way keeps the names already there, since objects it deleted the first time may no longer be found
109
110
  - A host refuses a push that places an object named in `deleted` of any version, and a process that copies versions between repositories copies none of them. Otherwise an old copy, such as a local clone, brings the data back
110
- - A copy of the repository, such as a mirror or a fork, applies the withdrawal by the names in `deleted`: every live version in it that reaches one of them is an affected version, including versions made only in the copy, and the named objects go even where no version reaches them
111
+ - A copy of the repository, such as a mirror, applies the withdrawal by the names in `deleted`: every live version in it that reaches one of them is an affected version, including versions made only in the copy, and the named objects go even where no version reaches them
111
112
 
112
113
  - `version.json` stays, as with retention, so every repository holds its history back to the first version. If the record itself holds the data (in `author`, `message` or `inputs`), it is rewritten without it before `expired.json` is put: the value in `author` or `message` is replaced with `withdrawn`, and the entries of `inputs` that hold it are dropped. `id`, `seq`, `parents` and the other fields stay as they were
114
+ - `by` and `message` of `expired.json` stay readable after the withdrawal, so they must not hold the data either: say why in general terms, such as "personal data published by mistake"
113
115
  - Mirrors keep their own copies. A mirror that copies `expired.json` with `"reason": "withdrawn"` deletes the metadata files and the shared objects named in `deleted`. The origin cannot force this; the host tells the mirrors it knows of
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "fdl-cli"
3
- version = "0.30.0"
3
+ version = "0.31.0"
4
4
  description = "Versions of a DuckLake catalog on object storage, kept the way Git keeps commits"
5
5
  readme = "README.md"
6
6
  license = "MIT"
@@ -977,6 +977,7 @@ def expire(
977
977
  since: str | None = typer.Option(None, help="Also keep those made at or after this time (ISO 8601)"),
978
978
  grace: str = typer.Option("7d", help="Also keep those made more recently than this: 7d, 24h or 30m"),
979
979
  by: str | None = typer.Option(None, help="Who or what takes them out, recorded in expired.json"),
980
+ message: str | None = typer.Option(None, "-m", "--message", help="Why they are taken out, recorded in expired.json"),
980
981
  ) -> None:
981
982
  """Take older versions out of retention: mark them and drop their catalogs.
982
983
 
@@ -985,7 +986,7 @@ def expire(
985
986
  """
986
987
  store = _store(remote)
987
988
  try:
988
- expired = repo.prune(store, keep=keep, since=since, grace=_duration(grace), by=by)
989
+ expired = repo.prune(store, keep=keep, since=since, grace=_duration(grace), by=by, message=message)
989
990
  except ERRORS as exc:
990
991
  raise _fail(exc) from exc
991
992
  typer.echo(f"Expired {len(expired)} version(s).")
@@ -1052,6 +1053,7 @@ def withdraw(
1052
1053
  ),
1053
1054
  yes: bool = typer.Option(False, "--yes", help="Do it. Without this, only say what would be done"),
1054
1055
  by: str | None = typer.Option(None, help="Who withdraws them, recorded in expired.json"),
1056
+ message: str | None = typer.Option(None, "-m", "--message", help="Why they are withdrawn, recorded in expired.json"),
1055
1057
  as_json: bool = typer.Option(False, "--json", help="Print the plan as JSON, listing the refs that block it instead of failing"),
1056
1058
  ) -> None:
1057
1059
  """Remove versions that hold data that must not be published.
@@ -1062,7 +1064,7 @@ def withdraw(
1062
1064
  version already past retention has no metadata, so then every data file and
1063
1065
  asset no live version reaches is deleted.
1064
1066
 
1065
- With --objects, a mirror or a fork applies a withdrawal made in the
1067
+ With --objects, a mirror applies a withdrawal made in the
1066
1068
  repository it was copied from.
1067
1069
  """
1068
1070
  store = _store(remote)
@@ -1100,7 +1102,7 @@ def withdraw(
1100
1102
  if not as_json:
1101
1103
  typer.echo("Nothing was changed. Run again with --yes to do this.")
1102
1104
  return
1103
- repo.withdraw(store, plan.versions, plan=plan, by=by)
1105
+ repo.withdraw(store, plan.versions, plan=plan, by=by, message=message)
1104
1106
  except ERRORS as exc:
1105
1107
  raise _fail(exc) from exc
1106
1108
  if not as_json:
@@ -779,6 +779,7 @@ def expire(
779
779
  *,
780
780
  reason: str = "retention",
781
781
  by: str | None = None,
782
+ message: str | None = None,
782
783
  deleted: dict[str, list[str]] | None = None,
783
784
  ) -> None:
784
785
  """Take a version out of retention: the mark first, then its catalogs.
@@ -792,7 +793,12 @@ def expire(
792
793
  held = _held(store)
793
794
  if version_id in held:
794
795
  raise RepoError(f"{held[version_id]} points at {version_id}, so it is kept")
795
- record: dict = {"expired_at": utc_now(), "reason": reason, **({"by": by} if by else {})}
796
+ record: dict = {
797
+ "expired_at": utc_now(),
798
+ "reason": reason,
799
+ **({"by": by} if by else {}),
800
+ **({"message": message} if message else {}),
801
+ }
796
802
  if deleted is not None:
797
803
  record["deleted"] = deleted
798
804
  try:
@@ -883,7 +889,7 @@ def plan_withdrawal(
883
889
  host that moves them itself.
884
890
 
885
891
  ``objects`` names shared objects another repository withdrew, as `deleted`
886
- of its `expired.json` does: a copy of it, such as a mirror or a fork,
892
+ of its `expired.json` does: a copy of it, such as a mirror,
887
893
  applies that withdrawal. Every live version that reaches one of them is
888
894
  affected too, and those objects go even where no version reaches them.
889
895
 
@@ -1111,7 +1117,12 @@ def _reached_assets(store: Store, version: Version, local: Path | None, setup: l
1111
1117
 
1112
1118
 
1113
1119
  def withdraw(
1114
- store: Store, version_ids: Iterable[str], *, plan: Withdrawal | None = None, by: str | None = None
1120
+ store: Store,
1121
+ version_ids: Iterable[str],
1122
+ *,
1123
+ plan: Withdrawal | None = None,
1124
+ by: str | None = None,
1125
+ message: str | None = None,
1115
1126
  ) -> Withdrawal:
1116
1127
  """Remove versions that hold data that must not be published.
1117
1128
 
@@ -1136,7 +1147,7 @@ def withdraw(
1136
1147
  store.delete([key for key in plan.deleted if not key.startswith(layout.ASSETS_DIR)])
1137
1148
  deleted = deleted_names(plan.deleted, read_config(store).data_dir)
1138
1149
  for version_id in plan.versions:
1139
- expire(store, version_id, reason="withdrawn", by=by, deleted=deleted)
1150
+ expire(store, version_id, reason="withdrawn", by=by, message=message, deleted=deleted)
1140
1151
  return plan
1141
1152
 
1142
1153
 
@@ -1256,6 +1267,7 @@ def prune(
1256
1267
  grace: dt.timedelta = dt.timedelta(days=7),
1257
1268
  reason: str = "retention",
1258
1269
  by: str | None = None,
1270
+ message: str | None = None,
1259
1271
  ) -> list[str]:
1260
1272
  """Take out of retention the versions `plan_retention` chooses. Returns their IDs, newest first.
1261
1273
 
@@ -1266,7 +1278,7 @@ def prune(
1266
1278
  held = _held(store)
1267
1279
  taken = [version_id for version_id in planned if version_id not in held]
1268
1280
  for version_id in taken:
1269
- expire(store, version_id, reason=reason, by=by)
1281
+ expire(store, version_id, reason=reason, by=by, message=message)
1270
1282
  return taken
1271
1283
 
1272
1284
 
@@ -275,8 +275,10 @@ def test_expire_marks_and_drops_the_metadata_but_keeps_the_record(tmp_path: Path
275
275
 
276
276
  def test_expire_records_who_took_the_version_out(tmp_path: Path, remote) -> None:
277
277
  first, _ = pushed_chain(tmp_path, remote, 2)
278
- repo.expire(remote, first.id, by="nightly retention")
279
- assert json.loads(remote.get(layout.version_expired(first.id)))["by"] == "nightly retention"
278
+ repo.expire(remote, first.id, by="nightly retention", message="Keep the newest 7 versions")
279
+ record = json.loads(remote.get(layout.version_expired(first.id)))
280
+ assert record["by"] == "nightly retention"
281
+ assert record["message"] == "Keep the newest 7 versions"
280
282
 
281
283
 
282
284
  def test_a_version_a_ref_holds_is_not_expired(tmp_path: Path, remote) -> None:
@@ -360,7 +360,7 @@ wheels = [
360
360
 
361
361
  [[package]]
362
362
  name = "fdl-cli"
363
- version = "0.28.0"
363
+ version = "0.29.0"
364
364
  source = { editable = "." }
365
365
  dependencies = [
366
366
  { name = "duckdb" },
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes