fdl-cli 0.22.0__tar.gz → 0.24.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 (108) hide show
  1. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/CHANGELOG.md +46 -0
  2. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/PKG-INFO +8 -3
  3. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/README.md +7 -2
  4. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/concepts/versions-and-refs.md +14 -3
  5. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/concepts/working-catalogs.md +6 -5
  6. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/getting-started.md +5 -3
  7. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/index.md +4 -3
  8. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/internals/from-write-to-read.md +1 -1
  9. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/internals/inside-a-repository.md +2 -2
  10. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/concepts/versions-and-refs.md +14 -3
  11. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/concepts/working-catalogs.md +6 -5
  12. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/getting-started.md +5 -3
  13. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/index.md +4 -3
  14. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/internals/from-write-to-read.md +1 -1
  15. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/internals/inside-a-repository.md +2 -2
  16. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/reference/cli.md +88 -12
  17. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/reference/python.md +24 -1
  18. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/spec/data-files.md +2 -0
  19. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/spec/refs.md +2 -2
  20. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/spec/versions.md +15 -3
  21. fdl_cli-0.24.0/docs/ja/spec/writing.md +115 -0
  22. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/reference/cli.md +87 -11
  23. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/reference/python.md +24 -1
  24. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/spec/data-files.md +2 -0
  25. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/spec/refs.md +2 -2
  26. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/spec/versions.md +15 -3
  27. fdl_cli-0.24.0/docs/spec/writing.md +115 -0
  28. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/pyproject.toml +1 -1
  29. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/catalog.py +198 -1
  30. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/cli.py +403 -34
  31. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/diff.py +5 -0
  32. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/layout.py +42 -0
  33. fdl_cli-0.24.0/src/fdl/merge.py +476 -0
  34. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/refs.py +5 -0
  35. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/repo.py +204 -30
  36. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/store.py +5 -0
  37. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/stores.py +44 -13
  38. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/version.py +6 -8
  39. fdl_cli-0.24.0/tests/test_cli.py +460 -0
  40. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/tests/test_http.py +67 -8
  41. fdl_cli-0.24.0/tests/test_merge.py +336 -0
  42. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/tests/test_objects.py +15 -9
  43. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/tests/test_profiles.py +12 -8
  44. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/tests/test_repo.py +66 -0
  45. fdl_cli-0.22.0/docs/ja/spec/writing.md +0 -58
  46. fdl_cli-0.22.0/docs/spec/writing.md +0 -58
  47. fdl_cli-0.22.0/tests/test_cli.py +0 -259
  48. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/.github/workflows/docs.yml +0 -0
  49. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/.github/workflows/publish.yml +0 -0
  50. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/.github/workflows/release.yml +0 -0
  51. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/.github/workflows/test.yml +0 -0
  52. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/.gitignore +0 -0
  53. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/.node-version +0 -0
  54. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/.python-version +0 -0
  55. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/CLAUDE.md +0 -0
  56. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/CONTRIBUTING.md +0 -0
  57. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/LICENSE +0 -0
  58. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/SECURITY.md +0 -0
  59. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/blume.config.ts +0 -0
  60. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/concepts/meta.ts +0 -0
  61. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/concepts/repositories.md +0 -0
  62. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/guides/building-a-host.md +0 -0
  63. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/guides/meta.ts +0 -0
  64. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/guides/mirrors.md +0 -0
  65. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/guides/public-and-private.md +0 -0
  66. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/guides/reading-without-duckdb.md +0 -0
  67. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/guides/serving-over-http.md +0 -0
  68. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/guides/stores.md +0 -0
  69. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/internals/ducklake-formats.md +0 -0
  70. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/internals/meta.ts +0 -0
  71. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/concepts/meta.ts +0 -0
  72. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/concepts/repositories.md +0 -0
  73. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/guides/building-a-host.md +0 -0
  74. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/guides/meta.ts +0 -0
  75. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/guides/mirrors.md +0 -0
  76. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/guides/public-and-private.md +0 -0
  77. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/guides/reading-without-duckdb.md +0 -0
  78. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/guides/serving-over-http.md +0 -0
  79. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/guides/stores.md +0 -0
  80. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/internals/ducklake-formats.md +0 -0
  81. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/internals/meta.ts +0 -0
  82. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/reference/meta.ts +0 -0
  83. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/spec/http.md +0 -0
  84. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/spec/index.md +0 -0
  85. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/spec/layout.md +0 -0
  86. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/spec/meta.ts +0 -0
  87. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/spec/reading.md +0 -0
  88. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/ja/stability.md +0 -0
  89. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/reference/meta.ts +0 -0
  90. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/spec/http.md +0 -0
  91. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/spec/index.md +0 -0
  92. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/spec/layout.md +0 -0
  93. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/spec/meta.ts +0 -0
  94. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/spec/reading.md +0 -0
  95. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/docs/stability.md +0 -0
  96. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/package-lock.json +0 -0
  97. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/package.json +0 -0
  98. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/public/CNAME +0 -0
  99. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/__init__.py +0 -0
  100. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/dataset.py +0 -0
  101. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/lineage.py +0 -0
  102. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/objects.py +0 -0
  103. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/profiles.py +0 -0
  104. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/src/fdl/py.typed +0 -0
  105. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/tests/http_repo.py +0 -0
  106. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/tests/test_dataset.py +0 -0
  107. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/tests/test_stores.py +0 -0
  108. {fdl_cli-0.22.0 → fdl_cli-0.24.0}/uv.lock +0 -0
@@ -1,6 +1,52 @@
1
1
  # CHANGELOG
2
2
 
3
3
 
4
+ ## v0.24.0 (2026-11-13)
5
+
6
+ ### Features
7
+
8
+ - List each table's columns in files.json ([#53](https://github.com/queria-io/fdl/pull/53),
9
+ [`98ae9fd`](https://github.com/queria-io/fdl/commit/98ae9fde19ec660778dd653add508b77bd882b54))
10
+
11
+ Readers without DuckDB can map Parquet columns by field_id from the catalog's column IDs and types,
12
+ without reading every file's footer.
13
+
14
+
15
+ ## v0.23.0 (2026-11-11)
16
+
17
+ ### Bug Fixes
18
+
19
+ - Re-ask the credential helper on 401, check IDs and paths, and specify merging
20
+ ([#50](https://github.com/queria-io/fdl/pull/50),
21
+ [`74b2d9b`](https://github.com/queria-io/fdl/commit/74b2d9b88dcf77f7ff6eb1c184919ccf62f51d88))
22
+
23
+ - Restore, pending commits, status and gc after review
24
+ ([#49](https://github.com/queria-io/fdl/pull/49),
25
+ [`73799be`](https://github.com/queria-io/fdl/commit/73799bedd7baedbd67054910b161e46cf5ea3883))
26
+
27
+ ### Features
28
+
29
+ - Fdl merge and fdl branch ([#51](https://github.com/queria-io/fdl/pull/51),
30
+ [`5e88708`](https://github.com/queria-io/fdl/commit/5e88708ade5ac84131a2a69dc285886c25af2fc6))
31
+
32
+ * feat: fdl merge and fdl branch
33
+
34
+ fdl merge merges another branch into the working catalog's branch, as the spec's Merging section
35
+ describes: a table only one side changed comes over, rows of a table both changed are merged by
36
+ the primary key both declare, and anything both changed differently is a conflict that makes no
37
+ version. A merge whose base is ours checks out theirs, and push then moves the branch there. fdl
38
+ branch lists, starts and deletes branches.
39
+
40
+ A push is now accepted when the version descends from what the branch holds, through every parent,
41
+ and is_ancestor no longer stops at seq, which a merge does not raise past the version it merged.
42
+
43
+ * fix: merge review findings: revert by first parent, temp names, table aliases, warnings
44
+
45
+ - Fdl revert, fdl push separate from fdl commit, and fdl gc
46
+ ([#48](https://github.com/queria-io/fdl/pull/48),
47
+ [`6e3ade9`](https://github.com/queria-io/fdl/commit/6e3ade956131cc9a5cd70fe1da6ebffb0aaa3bb7))
48
+
49
+
4
50
  ## v0.22.0 (2026-11-10)
5
51
 
6
52
  ### Features
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: fdl-cli
3
- Version: 0.22.0
3
+ Version: 0.24.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/
@@ -77,6 +77,7 @@ Then make a version and move `main` to it:
77
77
 
78
78
  ```bash
79
79
  fdl commit work/lake.sqlite -m "First towns" --author alice
80
+ fdl push work/lake.sqlite
80
81
  fdl log s3://my-bucket/towns/
81
82
  ```
82
83
 
@@ -100,18 +101,22 @@ Credentials and the endpoint come from boto3's usual places (`AWS_*` environment
100
101
  | --- | --- |
101
102
  | `fdl init <remote>` | Start a repository (`fdl.json` and `HEAD`) |
102
103
  | `fdl checkout <remote> <working>` | Make a working catalog from the version `main` holds |
103
- | `fdl commit <working> -m … --author …` | Freeze the working catalog into a version and push it |
104
+ | `fdl commit <working> -m … --author …` | Freeze the working catalog into a version |
105
+ | `fdl push <working>` | Upload the committed version and move `main` to it |
104
106
  | `fdl log <remote>` | List versions from `main` back to the first |
105
107
  | `fdl status <working>` | What the working catalog changed since the checkout |
106
108
  | `fdl diff <remote> [version]` | What a version changed since its parent: tables, rows, columns, data files, descriptions |
107
109
  | `fdl show <remote> [version]` | A version's record, its tables and its changes |
108
110
  | `fdl url <remote> [--attach]` | Print the catalog URL of the version `main` holds, or the whole `ATTACH` statement |
109
111
  | `fdl tag <remote> [name] [version]` | List tags, tag a version, or delete a tag (`-d`) |
112
+ | `fdl branch <remote> [name] [version]` | List branches, start a branch at a version, or delete a branch (`-d`) |
113
+ | `fdl merge <ref> <working> --author …` | Merge another branch into the working catalog's branch, rows matched by primary key |
110
114
  | `fdl expire <remote> --keep N` | Mark older versions as past retention and delete their catalogs |
115
+ | `fdl gc <remote> --yes` | Delete data files no live version reaches, after the grace period |
111
116
  | `fdl withdraw <remote> <version>…` | Remove versions that hold data that must not be published |
112
117
  | `fdl assets <folder>` | List files for an asset column (path, sha256, bytes, media type) |
113
118
 
114
- A push that is not built on what `main` holds now is refused: check out again and redo the work.
119
+ A push that is not built on what `main` holds now is refused: check out again and redo the work, or work on a branch and merge it.
115
120
 
116
121
  ## Python
117
122
 
@@ -57,6 +57,7 @@ Then make a version and move `main` to it:
57
57
 
58
58
  ```bash
59
59
  fdl commit work/lake.sqlite -m "First towns" --author alice
60
+ fdl push work/lake.sqlite
60
61
  fdl log s3://my-bucket/towns/
61
62
  ```
62
63
 
@@ -80,18 +81,22 @@ Credentials and the endpoint come from boto3's usual places (`AWS_*` environment
80
81
  | --- | --- |
81
82
  | `fdl init <remote>` | Start a repository (`fdl.json` and `HEAD`) |
82
83
  | `fdl checkout <remote> <working>` | Make a working catalog from the version `main` holds |
83
- | `fdl commit <working> -m … --author …` | Freeze the working catalog into a version and push it |
84
+ | `fdl commit <working> -m … --author …` | Freeze the working catalog into a version |
85
+ | `fdl push <working>` | Upload the committed version and move `main` to it |
84
86
  | `fdl log <remote>` | List versions from `main` back to the first |
85
87
  | `fdl status <working>` | What the working catalog changed since the checkout |
86
88
  | `fdl diff <remote> [version]` | What a version changed since its parent: tables, rows, columns, data files, descriptions |
87
89
  | `fdl show <remote> [version]` | A version's record, its tables and its changes |
88
90
  | `fdl url <remote> [--attach]` | Print the catalog URL of the version `main` holds, or the whole `ATTACH` statement |
89
91
  | `fdl tag <remote> [name] [version]` | List tags, tag a version, or delete a tag (`-d`) |
92
+ | `fdl branch <remote> [name] [version]` | List branches, start a branch at a version, or delete a branch (`-d`) |
93
+ | `fdl merge <ref> <working> --author …` | Merge another branch into the working catalog's branch, rows matched by primary key |
90
94
  | `fdl expire <remote> --keep N` | Mark older versions as past retention and delete their catalogs |
95
+ | `fdl gc <remote> --yes` | Delete data files no live version reaches, after the grace period |
91
96
  | `fdl withdraw <remote> <version>…` | Remove versions that hold data that must not be published |
92
97
  | `fdl assets <folder>` | List files for an asset column (path, sha256, bytes, media type) |
93
98
 
94
- A push that is not built on what `main` holds now is refused: check out again and redo the work.
99
+ A push that is not built on what `main` holds now is refused: check out again and redo the work, or work on a branch and merge it.
95
100
 
96
101
  ## Python
97
102
 
@@ -56,7 +56,7 @@ Refs are the only files in a repository that change. Everything else is written
56
56
 
57
57
  ## Moving a branch
58
58
 
59
- A branch moves forward only. A new version can become `main` when its `parents` include the version `main` holds now. This is a fast-forward in Git's terms.
59
+ A branch moves forward only. A new version can become `main` when it descends from the version `main` holds now: that version is reached by following `parents`. This is a fast-forward in Git's terms.
60
60
 
61
61
  ```
62
62
  main → A
@@ -64,9 +64,20 @@ main → A
64
64
  Bob checked out A too, commits C (parent A), pushes: refused
65
65
  ```
66
66
 
67
- Bob's push is refused because C is not built on B. If it were accepted, B would vanish from the history of `main` with no one deciding that. Bob checks out B and makes his change again.
67
+ Bob's push is refused because C is not built on B. If it were accepted, B would vanish from the history of `main` with no one deciding that. Bob checks out B and makes his change again. Redoing the change on the new version is usually a matter of running the same SQL again.
68
68
 
69
- FDL does not merge rows. Merging two DuckLake catalogs would mean deciding which row wins when both sides changed it, and DuckLake gives tables no identity across catalogs that would make that safe. Redoing the change on the new version is usually a matter of running the same SQL again.
69
+ ## Merging
70
+
71
+ Work that takes longer goes on a branch of its own, and is merged into `main` when it is ready:
72
+
73
+ ```
74
+ main → A → B
75
+ \
76
+ feature C
77
+ fdl merge refs/heads/feature on main makes M (parents B, C): main → M
78
+ ```
79
+
80
+ The merge compares each table in three versions: B, C and their common ancestor A. A table only one branch changed comes over as that branch holds it. When both changed the same table, the rows are matched by the `primary_key` both declare in `dataset.json`, and a row only one branch changed comes over. A row both changed differently, or a table without a primary key that both changed, is a conflict, and then no version is made. A row number added for the merge is not a primary key: it does not say which rows are the same row. See [Merging](/spec/writing#merging).
70
81
 
71
82
  Moving a branch back, to undo a version, is allowed only when asked for explicitly. The version that was undone stays in the repository and in the history.
72
83
 
@@ -11,7 +11,8 @@ A working catalog is a DuckLake catalog in a SQLite file, on the writer's own di
11
11
  | --- | --- | --- |
12
12
  | check out | `fdl checkout` | Copy the catalog of the branch's version into SQLite, and remember that version |
13
13
  | write | any DuckDB client | DuckLake writes Parquet into the repository and bookkeeping into SQLite |
14
- | commit | `fdl commit` | Freeze the last snapshot into a new version, upload it, move the branch |
14
+ | commit | `fdl commit` | Freeze the last snapshot into a new version, kept beside the working catalog |
15
+ | push | `fdl push` | Upload the version and move the branch to it |
15
16
 
16
17
  Checking out copies DuckLake's bookkeeping tables from the frozen DuckDB file into SQLite as they are. Freezing does the reverse. Neither rewrites a Parquet file, so both are fast even for a large dataset: the catalog is small and the data stays where it is.
17
18
 
@@ -19,7 +20,7 @@ Checking out copies DuckLake's bookkeeping tables from the frozen DuckDB file in
19
20
 
20
21
  A working catalog has to be written by DuckDB and kept between sessions. SQLite does both without a database server, works the same on a laptop and in a container, and copies in and out of DuckDB's format without loss.
21
22
 
22
- There is one kind of working catalog. A host that writes on behalf of its users (a scheduled import, a web form) checks out, writes and commits the same way a person does on a laptop. When two of them commit at once, the conditional write on the ref settles it: one wins, and the other checks out again.
23
+ There is one kind of working catalog. A host that writes on behalf of its users (a scheduled import, a web form) checks out, writes, commits and pushes the same way a person does on a laptop. When two of them push at once, the conditional write on the ref settles it: one wins, and the other checks out again.
23
24
 
24
25
  ## Attaching
25
26
 
@@ -33,15 +34,15 @@ ATTACH 'ducklake:work/lake.sqlite' AS lake (
33
34
  );
34
35
  ```
35
36
 
36
- - `DATA_PATH` is the repository's data folder, so new Parquet files land where readers will look for them. For a repository over HTTP it is a folder beside the working catalog instead, and `fdl commit` uploads the new files (see [Pushing over HTTP](/spec/http#writing-to-it))
37
+ - `DATA_PATH` is the repository's data folder, so new Parquet files land where readers will look for them. For a repository over HTTP it is a folder beside the working catalog instead, and `fdl push` uploads the new files (see [Pushing over HTTP](/spec/http#writing-to-it))
37
38
  - `DATA_INLINING_ROW_LIMIT 0` keeps every row out of the catalog. A version must not carry inlined rows, and `fdl commit` refuses a working catalog that holds some
38
39
  - `META_TYPE 'sqlite'` has to be stated. Left to guess from the file, DuckDB passes an option to SQLite that SQLite rejects
39
40
 
40
- ## Data files written before a commit
41
+ ## Data files written before a push
41
42
 
42
43
  DuckLake writes Parquet as you go, so data files reach the repository before any version names them. Readers never see them: a reader only opens catalogs of versions, and no version names those files yet.
43
44
 
44
- A file that stays unnamed for longer than the grace period (7 days by default) may be deleted by maintenance. Commit within that time. If a commit is refused because a file it names is missing, rebuild the table in the working catalog and commit again.
45
+ A file that stays unnamed for longer than the grace period (7 days by default) may be deleted by maintenance. Push within that time. If a push is refused because a file it names is missing, rebuild the table in the working catalog, commit and push again. A version committed and never pushed names its files only on your disk, so they are deleted in the same way.
45
46
 
46
47
  ## Snapshots in the working catalog
47
48
 
@@ -76,13 +76,14 @@ Every version carries a `dataset.json` that says what it holds. Write one next t
76
76
 
77
77
  Only `name` and `title` are required. `fdl commit` checks the file against the catalog and fills in each table's row count and each column's type.
78
78
 
79
- ## Commit
79
+ ## Commit and push
80
80
 
81
81
  ```bash
82
82
  fdl commit work/lake.sqlite -m "First towns" --author alice
83
+ fdl push work/lake.sqlite
83
84
  ```
84
85
 
85
- `commit` freezes the working catalog into a version, uploads it and moves `main` to it. It prints `refs/heads/main -> 019a3c4e-… (version 1)`. The repository now holds:
86
+ `commit` freezes the working catalog into a version on your disk. `push` uploads it and moves `main` to it, and prints `refs/heads/main -> 019a3c4e-… (version 1)`. The repository now holds:
86
87
 
87
88
  ```
88
89
  towns/
@@ -134,8 +135,9 @@ INSERT INTO lake.main.towns SELECT * FROM 'towns-2026.csv';
134
135
 
135
136
  ```bash
136
137
  fdl commit work/lake.sqlite -m "Add 2026" --author alice
138
+ fdl push work/lake.sqlite
137
139
  ```
138
140
 
139
141
  The new version lists the first as its parent. Both catalogs name the first Parquet file; only the second names the new one.
140
142
 
141
- If someone else committed in between, the commit is refused, because the new version would not be built on what `main` holds now. Check out again and redo the change. [Versions and refs](/concepts/versions-and-refs) explains why.
143
+ If someone else pushed in between, the push is refused, because the new version would not be built on what `main` holds now. Check out again and redo the change. [Versions and refs](/concepts/versions-and-refs) explains why.
@@ -30,7 +30,7 @@ FDL is meant for data that is published, read by many and written by few:
30
30
  - a dataset maintained by a team, where a change has to be reviewed before readers see it
31
31
  - copies of the same dataset on several hosts (mirrors)
32
32
 
33
- It is not a transactional database. Writers do not merge rows. Two people who push at once are settled by the store: the first push wins and the second is refused and has to build again on the new version.
33
+ It is not a transactional database. Two people who push at once are settled by the store: the first push wins and the second is refused. The second builds again on the new version, or works on a branch of its own and merges it, rows matched by the table's primary key.
34
34
 
35
35
  ## FDL and Git
36
36
 
@@ -45,10 +45,11 @@ FDL keeps a catalog's versions the way Git keeps a project's commits. If you kno
45
45
  | Branch, tag, `HEAD` | `refs/heads/`, `refs/tags/`, `HEAD` |
46
46
  | Working tree | Working catalog (SQLite on your disk) |
47
47
  | `git init --bare` | `fdl init` |
48
- | `git commit` and `git push` | `fdl commit` |
48
+ | `git commit`, `git push` | `fdl commit`, `fdl push` |
49
49
  | `git log`, `git tag` | `fdl log`, `fdl tag` |
50
+ | `git branch`, `git merge` | `fdl branch`, `fdl merge` |
50
51
 
51
- FDL does not merge, so a version has one parent. [From write to read](/internals/from-write-to-read) follows the files through a commit, step by step.
52
+ A version has one parent, or two when it merges another branch. [From write to read](/internals/from-write-to-read) follows the files through a commit, step by step.
52
53
 
53
54
  FDL is in beta. [Stability](/stability) says what stays the same across releases.
54
55
 
@@ -30,7 +30,7 @@ Three things differ on purpose:
30
30
 
31
31
  - A version's ID is a UUIDv7, not a hash of its content. Two DuckDB releases can write the same catalog as different bytes, so a content hash would change with the tool. The sha256 in `version.json` checks the content instead
32
32
  - There are no packfiles. Each file is its own object in the store, so a reader fetches only the parts of a Parquet file it needs
33
- - There is no merge. A version has one parent, and a writer whose push is refused builds again on the newer version
33
+ - A merge matches rows by the primary key that `dataset.json` declares, not by lines or files. Two branches that changed the same table without one are a conflict (see [Merging](/spec/writing#merging))
34
34
 
35
35
  ## Writing a version
36
36
 
@@ -40,7 +40,7 @@ No ref and no version names the file, so no reader can reach it. If the writer g
40
40
 
41
41
  ## The first commit
42
42
 
43
- `fdl commit` does its work in this order:
43
+ `fdl commit` does steps 1 to 4 on the writer's disk, and `fdl push` does the rest, in this order:
44
44
 
45
45
  1. Copy the working catalog from SQLite into a DuckDB file, keeping the snapshots up to the last one
46
46
  2. Set the catalog's `data_path` to the repository's data folder, and refuse if any file is recorded with an absolute path elsewhere
@@ -62,7 +62,7 @@ versions/019a2f10-…/version.json
62
62
  data/main/towns/ducklake-0199f1….parquet
63
63
  ```
64
64
 
65
- The order is what keeps readers safe. A reader starts from a ref, and the ref is written last. If the commit stops after step 6, 7 or 8, the repository holds a version folder no ref points at. Readers never see it, and it changes nothing.
65
+ The order is what keeps readers safe. A reader starts from a ref, and the ref is written last. If the push stops after step 6, 7 or 8, the repository holds a version folder no ref points at. Readers never see it, and it changes nothing.
66
66
 
67
67
  `version.json` is written after the catalog and `dataset.json` for the same reason: a tool that lists `versions/` can treat a folder without `version.json` as unfinished.
68
68
 
@@ -56,7 +56,7 @@ HEAD ref: refs/heads/main
56
56
 
57
57
  ## ブランチを動かす
58
58
 
59
- ブランチは前へだけ動きます。新しいバージョンが `main` になれるのは、その `parents` に、いま `main` が指すバージョンが入っているときです。Git でいう fast-forward です。
59
+ ブランチは前へだけ動きます。新しいバージョンが `main` になれるのは、いま `main` が指すバージョンの子孫であるときです。子孫とは、`parents` をたどるとそのバージョンに着くバージョンです。Git でいう fast-forward です。
60
60
 
61
61
  ```
62
62
  main → A
@@ -64,9 +64,20 @@ main → A
64
64
  Bob も A をチェックアウトしていて、C(親 A)をコミットして push: 断られる
65
65
  ```
66
66
 
67
- C は B の上に積まれていないので、Bob の push は断られます。受け付けると、誰も決めていないのに B が `main` の履歴から消えてしまいます。Bob は B をチェックアウトし、変更をやり直します。
67
+ C は B の上に積まれていないので、Bob の push は断られます。受け付けると、誰も決めていないのに B が `main` の履歴から消えてしまいます。Bob は B をチェックアウトし、変更をやり直します。新しいバージョンの上でのやり直しは、たいてい同じ SQL を実行し直すだけで済みます。
68
68
 
69
- FDL は行をマージしません。2 つの DuckLake カタログをマージするには、両方で変わった行のどちらを残すかを決める必要があります。DuckLake には、カタログをまたいで表の同一性を示す情報がないので、安全に決められません。新しいバージョンの上でのやり直しは、たいてい同じ SQL を流し直すだけで済みます。
69
+ ## マージ
70
+
71
+ 時間のかかる作業は自分のブランチで進め、できあがったら `main` にマージします。
72
+
73
+ ```
74
+ main → A → B
75
+ \
76
+ feature C
77
+ main で fdl merge refs/heads/feature を実行すると M(親 B、C)ができる: main → M
78
+ ```
79
+
80
+ マージは、テーブルごとに B、C、両者の共通の祖先 A の 3 つのバージョンを比較します。片方のブランチだけが変えたテーブルは、そのブランチの内容を取り込みます。両方が同じテーブルを変えたときは、両方が `dataset.json` で宣言した `primary_key` で行を照合し、片方だけが変えた行を取り込みます。両方が違う形に変えた行と、主キーの無いテーブルを両方が変えたときは衝突になり、バージョンは作りません。マージのために付けた行番号は主キーになりません。どの行が同じ行かを示さないためです。[マージ](/ja/spec/writing#マージ)を参照してください。
70
81
 
71
82
  バージョンを取り消すためにブランチを後ろへ戻すのは、明示的に指示したときだけできます。取り消したバージョンも、リポジトリと履歴には残ります。
72
83
 
@@ -11,7 +11,8 @@ description: 書き込みをする場所です。SQLite の DuckLake カタロ
11
11
  | --- | --- | --- |
12
12
  | チェックアウト | `fdl checkout` | ブランチのバージョンのカタログを SQLite に写し、そのバージョンを覚える |
13
13
  | 書く | DuckDB のクライアント | DuckLake が Parquet をリポジトリへ、管理用の行を SQLite へ書く |
14
- | コミット | `fdl commit` | 最後のスナップショットを新しいバージョンに固め、アップロードし、ブランチを動かす |
14
+ | コミット | `fdl commit` | 最後のスナップショットを新しいバージョンに固め、作業カタログの隣に置く |
15
+ | push | `fdl push` | バージョンをアップロードし、ブランチをそこへ動かす |
15
16
 
16
17
  チェックアウトでは、DuckLake の管理用の表を、固めた DuckDB ファイルから SQLite へそのまま写します。固めるときはその逆です。どちらも Parquet ファイルは書き換えないので、大きなデータセットでもすぐ終わります。カタログは小さく、データはその場に残ります。
17
18
 
@@ -19,7 +20,7 @@ description: 書き込みをする場所です。SQLite の DuckLake カタロ
19
20
 
20
21
  作業カタログは、DuckDB から書けて、作業をまたいで残せる必要があります。SQLite はデータベースサーバーなしでその両方ができ、手元のパソコンでもコンテナでも同じように動き、DuckDB の形式との間で欠けなく写せます。
21
22
 
22
- 作業カタログは 1 種類です。利用者の代わりに書くホスト(定期の取り込みや Web のフォームなど)も、人がパソコンでするのと同じ手順でチェックアウトし、書き、コミットします。2 つが同時にコミットしたときは、ref の条件付き書き込みで決まります。一方が通り、もう一方はチェックアウトし直します。
23
+ 作業カタログは 1 種類です。利用者の代わりに書くホスト(定期の取り込みや Web のフォームなど)も、人がパソコンでするのと同じ手順でチェックアウトし、書き、コミットして push します。2 つが同時に push したときは、ref の条件付き書き込みで決まります。一方が通り、もう一方はチェックアウトし直します。
23
24
 
24
25
  ## ATTACH の仕方
25
26
 
@@ -33,15 +34,15 @@ ATTACH 'ducklake:work/lake.sqlite' AS lake (
33
34
  );
34
35
  ```
35
36
 
36
- - `DATA_PATH` はリポジトリのデータフォルダです。新しい Parquet ファイルは、読み手が探す場所に書かれます。HTTP 越しのリポジトリでは、かわりに作業カタログの隣のフォルダになり、新しいファイルは `fdl commit` が上げます([HTTP での push](/ja/spec/http#書き方))
37
+ - `DATA_PATH` はリポジトリのデータフォルダです。新しい Parquet ファイルは、読み手が探す場所に書かれます。HTTP 越しのリポジトリでは、かわりに作業カタログの隣のフォルダになり、新しいファイルは `fdl push` が上げます([HTTP での push](/ja/spec/http#書き方))
37
38
  - `DATA_INLINING_ROW_LIMIT 0` で、行をカタログの中に入れないようにします。バージョンはカタログの中に行を持てないので、行を持つ作業カタログは `fdl commit` が断ります
38
39
  - `META_TYPE 'sqlite'` は省略できません。省くと DuckDB がファイルから種類を推測し、SQLite が受け付けないオプションを渡してしまいます
39
40
 
40
- ## コミット前に書かれたデータファイル
41
+ ## push 前に書かれたデータファイル
41
42
 
42
43
  DuckLake は書くそばから Parquet を書くので、データファイルは、それを参照するバージョンより先にリポジトリに届きます。読み手には見えません。読み手はバージョンのカタログしか開かず、まだどのバージョンもそのファイルを参照していないからです。
43
44
 
44
- どこからも参照されないまま猶予期間(既定で 7 日)を過ぎたファイルは、保守で消されることがあります。その前にコミットしてください。参照しているファイルが無いと言われてコミットが断られたら、作業カタログで表を作り直してコミットし直してください。
45
+ どこからも参照されないまま猶予期間(既定で 7 日)を過ぎたファイルは、保守で消されることがあります。その前に push してください。参照しているファイルが無いと言われて push が断られたら、作業カタログで表を作り直し、コミットと push をやり直してください。コミットしたまま push しなかったバージョンは手元でしかファイルを参照していないので、そのファイルも同じように消されます。
45
46
 
46
47
  ## 作業カタログのスナップショット
47
48
 
@@ -76,13 +76,14 @@ SELECT * FROM 'towns.csv';
76
76
 
77
77
  必須なのは `name` と `title` だけです。`fdl commit` がこのファイルをカタログと照らし合わせ、表ごとの行数と列ごとの型を書き足します。
78
78
 
79
- ## コミットする
79
+ ## コミットして push する
80
80
 
81
81
  ```bash
82
82
  fdl commit work/lake.sqlite -m "First towns" --author alice
83
+ fdl push work/lake.sqlite
83
84
  ```
84
85
 
85
- `commit` は作業カタログを固めてバージョンにし、アップロードして、`main` をそこへ動かします。`refs/heads/main -> 019a3c4e-… (version 1)` と表示します。リポジトリは次のようになります。
86
+ `commit` は作業カタログを固めて手元でバージョンにします。`push` はそれをアップロードして `main` をそこへ動かし、`refs/heads/main -> 019a3c4e-… (version 1)` と表示します。リポジトリは次のようになります。
86
87
 
87
88
  ```
88
89
  towns/
@@ -134,8 +135,9 @@ INSERT INTO lake.main.towns SELECT * FROM 'towns-2026.csv';
134
135
 
135
136
  ```bash
136
137
  fdl commit work/lake.sqlite -m "Add 2026" --author alice
138
+ fdl push work/lake.sqlite
137
139
  ```
138
140
 
139
141
  新しいバージョンは、最初のバージョンを親として記録します。最初の Parquet ファイルは両方のカタログが参照し、新しいファイルは 2 つめのカタログだけが参照します。
140
142
 
141
- 途中でほかの人がコミットしていたら、このコミットは断られます。新しいバージョンが、いまの `main` の上に積まれていないためです。チェックアウトし直して、変更をやり直してください。理由は[バージョンと ref](/ja/concepts/versions-and-refs) で説明しています。
143
+ 途中でほかの人が push していたら、この push は断られます。新しいバージョンが、いまの `main` の上に積まれていないためです。チェックアウトし直して、変更をやり直してください。理由は[バージョンと ref](/ja/concepts/versions-and-refs) で説明しています。
@@ -30,7 +30,7 @@ FDL は、公開して多くの人が読み、少ない人が書くデータに
30
30
  - チームで整備し、読み手に見せる前に変更を確認するデータセット
31
31
  - 同じデータセットを複数のホストに置く写し(ミラー)
32
32
 
33
- FDL はトランザクションのためのデータベースではありません。書き手どうしで行をマージしません。2 人が同時に push したときは置き場が決めます。先に push したほうが通り、後のほうは断られて、新しいバージョンの上に作り直します。
33
+ FDL はトランザクションのためのデータベースではありません。2 人が同時に push したときは置き場が決めます。先に push したほうが通り、後のほうは断られます。後の書き手は新しいバージョンの上に作り直すか、自分のブランチで作業してマージします。マージではテーブルの主キーで行を照合します。
34
34
 
35
35
  ## FDL と Git
36
36
 
@@ -45,10 +45,11 @@ FDL は、Git がプロジェクトのコミットを残すのと同じ形で、
45
45
  | ブランチ・タグ・`HEAD` | `refs/heads/`・`refs/tags/`・`HEAD` |
46
46
  | 作業ツリー | 作業カタログ(手元の SQLite) |
47
47
  | `git init --bare` | `fdl init` |
48
- | `git commit` と `git push` | `fdl commit` |
48
+ | `git commit`、`git push` | `fdl commit`、`fdl push` |
49
49
  | `git log`・`git tag` | `fdl log`・`fdl tag` |
50
+ | `git branch`・`git merge` | `fdl branch`・`fdl merge` |
50
51
 
51
- FDL はマージをしないので、バージョンの親は 1 つです。[書いてから読まれるまで](/ja/internals/from-write-to-read)で、コミットのときにファイルがどう動くかを順に追えます。
52
+ バージョンの親は 1 つです。別のブランチをマージしたバージョンは親を 2 つ持ちます。[書いてから読まれるまで](/ja/internals/from-write-to-read)で、コミットのときにファイルがどう動くかを順に追えます。
52
53
 
53
54
  FDL はベータです。リリースをまたいで変わらないものは[安定性](/ja/stability)に書いています。
54
55
 
@@ -30,7 +30,7 @@ FDL は Git の役割と名前をそのまま使い、保存の仕方は独自
30
30
 
31
31
  - バージョンの ID は UUIDv7 で、中身のハッシュではありません。DuckDB のリリースが違うと、同じカタログでも違うバイト列で書かれることがあり、中身のハッシュは道具によって変わってしまうためです。中身の確認には `version.json` の sha256 を使います
32
32
  - packfile はありません。ファイルはそれぞれストアの 1 つのオブジェクトなので、読み手は Parquet ファイルのうち要る部分だけを取りに行けます
33
- - マージはありません。バージョンの親は 1 つです。push を断られた書き手は、新しいバージョンの上で作り直します
33
+ - マージは行やファイルではなく、`dataset.json` が宣言する主キーで行を照合します。主キーの無いテーブルを 2 つのブランチが両方変えたときは衝突になります([マージ](/ja/spec/writing#マージ))
34
34
 
35
35
  ## バージョンを書く
36
36
 
@@ -40,7 +40,7 @@ data/main/towns/ducklake-0199f1….parquet
40
40
 
41
41
  ## 最初のコミット
42
42
 
43
- `fdl commit` は次の順に進みます。
43
+ 1〜4 は `fdl commit` が書き手の手元で行い、残りは `fdl push` が行います。次の順に進みます。
44
44
 
45
45
  1. 作業カタログを SQLite から DuckDB のファイルへ写し、最後のスナップショットまでを残す
46
46
  2. カタログの `data_path` をリポジトリのデータフォルダにし、ほかの場所を絶対パスで指すファイルがあれば断る
@@ -62,7 +62,7 @@ versions/019a2f10-…/version.json
62
62
  data/main/towns/ducklake-0199f1….parquet
63
63
  ```
64
64
 
65
- 読み手の安全はこの順番で守られます。読み手は ref から読み始め、ref は最後に書かれます。コミットが 6、7、8 の段階で止まっても、リポジトリに残るのは、どの ref も指していないバージョンのフォルダです。読み手には見えず、何も変わりません。
65
+ 読み手の安全はこの順番で守られます。読み手は ref から読み始め、ref は最後に書かれます。push が 6、7、8 の段階で止まっても、リポジトリに残るのは、どの ref も指していないバージョンのフォルダです。読み手には見えず、何も変わりません。
66
66
 
67
67
  `version.json` をカタログと `dataset.json` のあとに書くのも同じ理由です。`versions/` の一覧を取るツールは、`version.json` の無いフォルダを書きかけとみなせます。
68
68
 
@@ -21,6 +21,8 @@ helper = "example-cli fdl-credential"
21
21
 
22
22
  fdl は `<helper> get` を実行し、標準入力に `protocol=`・`host=`・`path=` の行と空行を渡して、出力の `password=` の行を読みます。何も出さないか、エラーで終わったら、トークンは無いものとします。トークンの保存と helper の書き込みは、ホストの側の道具が行います。
23
23
 
24
+ helper から得たトークンにホストが 401 を返すと、fdl は helper をもう一度実行し、別のトークンが返ればそれでリクエストを送り直します。helper は期限の短いトークンを渡せます。`FDL_TOKEN` のトークンは取り直しません。
25
+
24
26
  ## fdl init
25
27
 
26
28
  ```bash
@@ -37,9 +39,9 @@ fdl checkout <remote> <working.sqlite> [--ref refs/heads/main] [--storage s3://b
37
39
 
38
40
  ブランチが指すバージョンのカタログから作業カタログ(SQLite の DuckLake)を作ります。最初のバージョンの前は空のものを作ります。隣の `<working.sqlite>.fdl.json` に、リポジトリ、ブランチ、元のバージョンを記録します。書くときの `ATTACH` 文を表示します。
39
41
 
40
- HTTP のリポジトリでは、新しいデータファイルは `<working.sqlite>.data/` に書かれ、コミットでアップロードされます。リポジトリに既にあるファイルは、その場所から HTTP で読みます。コミットはアップロードを終えると、新しいバージョンから作業カタログを作り直して手元の写しを削除するので、このフォルダにはまだコミットしていないファイルだけが残ります。
42
+ HTTP のリポジトリでは、新しいデータファイルは `<working.sqlite>.data/` に書かれ、push でアップロードされます。リポジトリに既にあるファイルは、その場所から HTTP で読みます。push はアップロードを終えると、新しいバージョンから作業カタログを作り直して手元の写しを削除するので、このフォルダにはまだ push していないファイルだけが残ります。
41
43
 
42
- `--storage` を付けると、作業カタログはリポジトリのストレージで直接データファイルを読み書きします。`--storage` にはそのストレージでのリポジトリの根を渡します。新しいファイルはその `data_dir` の下に直接書かれるので、コミットでアップロードするものはありません。鍵は `AWS_*` の環境変数(R2 などの S3 互換ストレージは `AWS_ENDPOINT_URL`)か、自分で作った DuckDB の secret から取ります。作業カタログに書くビルドにも同じ鍵が要ります。
44
+ `--storage` を付けると、作業カタログはリポジトリのストレージで直接データファイルを読み書きします。`--storage` にはそのストレージでのリポジトリの根を渡します。新しいファイルはその `data_dir` の下に直接書かれるので、push でアップロードするものはありません。鍵は `AWS_*` の環境変数(R2 などの S3 互換ストレージは `AWS_ENDPOINT_URL`)か、自分で作った DuckDB の secret から取ります。作業カタログに書くビルドにも同じ鍵が要ります。
43
45
 
44
46
  バージョンの保持期間が過ぎているとき、カタログの sha256 が `version.json` の記録と違うとき、カタログがデータフォルダの外のデータファイルを指しているときは断られます。
45
47
 
@@ -49,27 +51,43 @@ HTTP のリポジトリでは、新しいデータファイルは `<working.sqli
49
51
  fdl commit <working.sqlite> -m "What changed" --author alice [--dataset dataset.json] [--allow-empty] [--assets files/]
50
52
  ```
51
53
 
52
- 作業カタログを、チェックアウトしたバージョンを親とする新しいバージョンに固め、アップロードし、条件付きでブランチを動かします。ブランチ、新しいバージョン ID、`seq` を表示します。
54
+ 作業カタログを、チェックアウトした(または最後に push した)バージョンを親とする新しいバージョンに固め、`fdl push` で送るまで `<working.sqlite>.pending/` に置きます。リポジトリは何も変わりません。新しいバージョン ID と `seq` を表示します。push する前にもう一度コミットすると、まだ push していないバージョンを置き換えます。
53
55
 
54
56
  バージョンはそれぞれ `dataset.json`([バージョン](/ja/spec/versions#datasetjson)を参照)で説明します。`--dataset` で指定したファイルか、なければいまのディレクトリの `dataset.json` か `dataset.yml` から読みます。そのフォルダより下にある `*.table.yml`(または `*.table.json`)のテーブルの説明も合わせて読みます。隠しフォルダの中は読みません。コマンドはそれをカタログと照らし合わせ、列の型、行数、カタログのコメントを書き足します。
55
57
 
56
- コマンドは、説明の隣の `README.md` と、そこにある `docs/` より下のファイル(隠しファイルを除く)をバージョンの tree に入れます。そのフォルダからのパスで `tree.json` を書き、リポジトリに無いものを書いたままの中身で `assets/<sha256>` にアップロードします([tree.json](/ja/spec/versions#treejson))。
58
+ コマンドは、説明の隣の `README.md` と、そこにある `docs/` より下のファイル(隠しファイルを除く)をバージョンの tree に入れます。そのフォルダからのパスで `tree.json` を書き、push がリポジトリに無いものを書いたままの中身で `assets/<sha256>` にアップロードします([tree.json](/ja/spec/versions#treejson))。
57
59
 
58
60
  あわせてテーブルごとの profile を書きます([profiles/](/ja/spec/versions#profiles))。読むのは、データファイルか列が親から変わったテーブルだけです。読めなかったテーブルには profile を書かず、警告を出してコミットを続けます。
59
61
 
60
- `asset: true` の印を付けた列は、ファイルの sha256 を持ちます([アセット](/ja/spec/versions#アセット))。コマンドはその列の値を読み、リポジトリに無いファイルを `--assets` のフォルダから `assets/<sha256>` にアップロードします。ファイルは中身で照合するので、フォルダの中のファイル名は問いません。
62
+ `asset: true` の印を付けた列は、ファイルの sha256 を持ちます([アセット](/ja/spec/versions#アセット))。コマンドはその列の値を読み、push がリポジトリに無いファイルを `--assets` のフォルダから `assets/<sha256>` にアップロードします。ファイルは中身で照合するので、フォルダの中のファイル名は問いません。
61
63
 
62
- 親と同じ中身になるとき([変更がないとき](/ja/spec/writing#変更がないとき))は `Nothing to commit` と表示し、ブランチを動かさずに終了コード 0 で終わります。同じ行を新しいファイルに書き直しただけの作り直しも、変更なしとみなします。`--allow-empty` を付けると、それでもバージョンを作ります。行を読めず判定できないときは、警告を出してバージョンを作ります。
64
+ 親と同じ中身になるとき([変更がないとき](/ja/spec/writing#変更がないとき))は `Nothing to commit` と表示し、何も作らずに終了コード 0 で終わります。同じ行を新しいファイルに書き直しただけの作り直しも、変更なしとみなします。`--allow-empty` を付けると、それでもバージョンを作ります。行を読めず判定できないときは、警告を出してバージョンを作ります。
63
65
 
64
66
  次のときは断られます。
65
67
 
66
68
  - `dataset.json` が無いとき、カタログに無い表や列を説明しているとき。形式が決めていないキーは、警告を出してそのまま残します
67
- - チェックアウトのあとにブランチが動いたとき。チェックアウトし直して作業をやり直す
68
69
  - 作業カタログが行をカタログの中に持っているとき
69
- - カタログが参照するデータファイルがリポジトリに無いとき
70
- - アセットの列が `varchar` でないとき、sha256 でない値を持つとき、リポジトリにも `--assets` にも無いファイルを指すとき
70
+ - アセットの列が `varchar` でないとき、sha256 でない値を持つとき
71
71
  - データファイルが、データディレクトリの外を指す絶対パスで記録されているとき
72
72
 
73
+ ## fdl push
74
+
75
+ ```bash
76
+ fdl push <working.sqlite>
77
+ ```
78
+
79
+ `fdl commit` が作ったバージョンをアップロードし、条件付きでブランチをそこへ動かします([書き込みの順番](/ja/spec/writing#書き込みの順番))。ブランチ、バージョン ID、`seq` を表示します。fast-forward の `fdl merge` のあとは、何もアップロードせず、ブランチをマージしたバージョンへ動かします。コミットしたものが無いときは `Nothing to push` と表示します。
80
+
81
+ 作業カタログがリポジトリに書いたデータファイルは push の前からありますが、push するまでどのバージョンも参照しません。push しなかったファイルは猶予期間のあとに削除されます。
82
+
83
+ 次のときは断られます。
84
+
85
+ - チェックアウトのあとにブランチが動き、バージョンがいまブランチの指すバージョンの子孫でないとき。チェックアウトし直して作業をやり直す
86
+ - カタログが参照するデータファイルがリポジトリに無いとき
87
+ - アセットの列が、リポジトリにも `--assets` にも無いファイルを指すとき
88
+
89
+ 断られても、コミットしたバージョンはそのまま残るので、原因を直してからもう一度送れます。
90
+
73
91
  ## fdl assets
74
92
 
75
93
  ```bash
@@ -92,7 +110,7 @@ ref が指すバージョンから最初のバージョンまで、最初の親
92
110
  fdl status <working.sqlite> [--json]
93
111
  ```
94
112
 
95
- 作業カタログが checkout してから何を変えたかを、`fdl diff` と同じ区分で表示します。元のバージョンと同じ内容なら `Nothing to commit` と表示します。`dataset.json` の文言はコミットまで比べません。
113
+ 作業カタログが checkout してから何を変えたかを、`fdl diff` と同じ区分で表示します。元のバージョンと同じ内容なら `Nothing to commit` と表示します。`dataset.json` の文言はコミットまで比べません。コミットしてまだ push していないバージョンがあれば、先にそれを表示し、変更はそのバージョンから数えます。`--json` では `pending` にその ID を入れます。fast-forward の `fdl merge` のあとは、`fdl push` でブランチが動くことを表示します。
96
114
 
97
115
  ## fdl diff
98
116
 
@@ -140,7 +158,55 @@ fdl tag <remote> <name> [<version>] # バージョンにタグを付ける(
140
158
  fdl tag <remote> <name> --delete
141
159
  ```
142
160
 
143
- `<version>` にはバージョン ID か、`refs/heads/main` のような ref を渡します。タグは一度作ると動かしません。別のバージョンを指す同じ名前のタグがあるときは断られます。保持期間を過ぎたバージョンにはタグを付けられません。タグを作るか消すと `refs.json` を書き直します。`fdl commit` もブランチを動かしたあとに書き直します。
161
+ `<version>` にはバージョン ID か、`refs/heads/main` のような ref を渡します。タグは一度作ると動かしません。別のバージョンを指す同じ名前のタグがあるときは断られます。保持期間を過ぎたバージョンにはタグを付けられません。タグを作るか消すと `refs.json` を書き直します。`fdl push` もブランチを動かしたあとに書き直します。
162
+
163
+ ## fdl branch
164
+
165
+ ```bash
166
+ fdl branch <remote> # ブランチを並べる
167
+ fdl branch <remote> <name> [<version>] # バージョンからブランチを作る(既定は HEAD が指すバージョン)
168
+ fdl branch <remote> <name> --delete
169
+ ```
170
+
171
+ `<version>` にはバージョン ID か、`refs/heads/main` のような ref を渡します。別のバージョンを指す同じ名前のブランチがあるときは断られます。同じバージョンなら何も変えません。保持期間を過ぎたバージョンからはブランチを作れません。`HEAD` が指すブランチは削除できません。ブランチは `fdl checkout --ref refs/heads/<name>` でチェックアウトします。ブランチを作るか削除すると `refs.json` を書き直します。
172
+
173
+ ## fdl revert
174
+
175
+ ```bash
176
+ fdl revert <version> <working.sqlite> --author <name> [-m <message>]
177
+ fdl push <working.sqlite>
178
+ ```
179
+
180
+ 作業カタログを `<version>` が持っていたテーブルとビューに書き戻し、`<version>` の `dataset.json` と `tree.json` で、`fdl commit` と同じく新しいバージョンをコミットします。作業カタログのコミットしていない変更は失われます。そのあと `fdl push` でブランチを前に進めます。間のバージョンは履歴に残り、読み続けられます。`<version>` から変わっていないテーブルはデータファイルをそのまま使い、変わったテーブルは `<version>` の時点の行から書き直します。`<version>` にはバージョン ID か ref を渡し、作業カタログをチェックアウトしたバージョンから最初の親をたどった履歴にあって(マージで取り込んだだけのバージョンは含みません)保持期間内のバージョンを指定します。そのバージョンがすでに `<version>` と同じものを持つときは、何も作りません。
181
+
182
+ 公開してはいけないデータを除くときは `fdl withdraw` を使います。revert は間のバージョンとそのデータファイルをそのまま残します。
183
+
184
+ ## fdl merge
185
+
186
+ ```bash
187
+ fdl merge <theirs> <working.sqlite> --author <name> [-m <message>]
188
+ fdl push <working.sqlite>
189
+ ```
190
+
191
+ 別のブランチを、作業カタログをチェックアウトしたブランチにマージします([マージ](/ja/spec/writing#マージ))。`<theirs>` には `refs/heads/feature` のような ref か、バージョン ID を渡します。基点は 2 つのバージョンの共通の祖先です。
192
+
193
+ - `<theirs>` が作業カタログのバージョンの履歴にすでにあるときは `Already up to date` と表示し、何も作りません
194
+ - 作業カタログのバージョンが `<theirs>` の履歴にあるときは、作業カタログを `<theirs>` でチェックアウトし直し、バージョンは作りません。そのあと `fdl push` でブランチをそこへ動かします(fast-forward)
195
+ - それ以外は、マージの結果を作業カタログに書き、マージのバージョンをコミットします。`parents` は作業カタログのバージョンと `<theirs>` です。`fdl push` はコミットと同じくそれをアップロードします。メッセージの既定は `Merge <theirs>` です
196
+
197
+ 基点から `<theirs>` だけが変えた・追加した・削除したテーブルは、`<theirs>` の内容を新しいデータファイルに書いて取り込みます。両方が変えたテーブルは、両方が `dataset.json` で宣言した `primary_key` で行をマージします。`<theirs>` だけが追加・変更・削除した行は、その変更を取り込みます。`dataset.json` と `tree.json` はキーごとにマージします。行数・型・NULL の可否は、マージしたカタログから書き直します。コマンドは、取り込んだテーブルと、`<theirs>` が追加・変更・削除した行数を表示します。`fdl commit` は説明を手元のファイルから読むので、`<theirs>` が `dataset.json` か `tree.json` を変えたときは警告を出します。次のコミットの前に、その変更を手元のファイルに反映してください。
198
+
199
+ 衝突があるときは、テーブルごとに、行の衝突は主キーの値で一覧を表示し、終了コード 1 で終わり、何も変えません。衝突になるのは次のときです。
200
+
201
+ - 両方が違う形に変えたテーブルに、両方が宣言する主キーが無いとき(ビューはその SQL で、そのようなテーブルと同じく比較します)
202
+ - 片方が削除したテーブルを、もう片方が変えたとき
203
+ - 両方が変えたテーブルの列か型が両者で違うとき、または両方が列を変えたとき
204
+ - 両方が違う形に変えた行があるとき、または主キーに `NULL` や重複があるとき
205
+ - `dataset.json` か `tree.json` の同じ値を、両方が違う形に変えたとき
206
+
207
+ 衝突しなくなるようにどちらかのブランチを直してから、もう一度マージします。
208
+
209
+ 作業カタログにコミットしていない変更があるとき、コミットして push していないバージョンがあるとき、2 つのバージョンに、ほかの共通の祖先の祖先でない共通の祖先が複数あるとき、基点か `<theirs>` が保持期間を過ぎているときは断られます。
144
210
 
145
211
  ## fdl withdraw
146
212
 
@@ -160,4 +226,14 @@ fdl withdraw <remote> <version>... [--yes]
160
226
  fdl expire <remote> [--keep 1] [--since 2026-10-01T00:00:00Z] [--ref refs/heads/main]
161
227
  ```
162
228
 
163
- ブランチの最初の親のつながりで、新しい `--keep` 個より古いバージョンの保持期間を終わらせます。`expired.json` を置き、カタログを消します。`--since` 以降に作ったバージョンと、ref が指すバージョンは残します。データファイルは消しません。
229
+ ブランチの最初の親のつながりで、新しい `--keep` 個より古いバージョンの保持期間を終わらせます。`expired.json` を置き、カタログを消します。`--since` 以降に作ったバージョンと、ref が指すバージョンは残します。データファイルは消しません。消すのは `fdl gc` です。
230
+
231
+ ## fdl gc
232
+
233
+ ```bash
234
+ fdl gc <remote> [--grace 7d] [--yes]
235
+ ```
236
+
237
+ どの生きているバージョンからも参照されず、`--grace`(`7d`、`24h`、`30m`)より前に書かれたデータファイルとアセットを削除します([共有オブジェクトを消してよいとき](/ja/spec/data-files#共有オブジェクトを消してよいとき))。保持期間を過ぎたバージョンだけが参照していたファイルと、作業カタログが書いて push しなかったファイルがこれに当たります。`--yes` を付けないときは、一覧を表示するだけです。
238
+
239
+ 生きているバージョンそれぞれの `files.json` と、行がアセットを持つバージョンのカタログを読みます。HTTP のリポジトリ(削除はホストが行う)と、`files.json` もカタログも無い生きているバージョンがあるときは断られます。