@@ -1117,6 +1117,11 @@ COMMANDS:
11171117 clean removes ALL froms the local Lake cache
11181118 services print configured remote cache services
11191119
1120+ STAGING COMMANDS:
1121+ stage <map> <dir> copy build outputs from the cache to a directory
1122+ unstage <dir> cache build outputs from a staging directory
1123+ put-staged <dir> upload build outputs from a staging directory
1124+
11201125See `lake cache help <command>` for more information on a specific command.
11211126```
11221127
@@ -1134,11 +1139,11 @@ OPTIONS:
11341139 --platform=<target-triple> with Reservoir or --repo, sets the platform
11351140 --toolchain=<name> with Reservoir or --repo, sets the toolchain
11361141 --scope=<remote-scope> scope for a custom endpoint
1137- --download-arts download artifacts now, not on demand
1142+ --mappings-only only download mappings, delay artifacts
11381143 --force-download redownload existing files
11391144
11401145Downloads build outputs for packages in the workspace from a remote cache
1141- service. The cache service used can be specifed via the `--service` option.
1146+ service. The cache service used can be specified via the `--service` option.
11421147Otherwise, Lake will the system default, or, if none is configured, Reservoir.
11431148See `lake cache services` for more information on how to configure services.
11441149
@@ -1165,17 +1170,16 @@ artifacts. If no mappings are found, Lake will backtrack the Git history up to
11651170`--max-revs`, looking for a revision with mappings. If `--max-revs` is 0, Lake
11661171will search the repository's entire history (or as far as Git will allow).
11671172
1168- With a named service and without a mappings file, Lake will only download
1169- the input-to-output mappings for packages. It will delay downloading of the
1170- corresponding artifacts to the next `lake build` that requires them. Using
1171- `--download-arts` will force Lake to download all artifacts eagerly.
1173+ By default, Lake will download both the input-to-output mappings and the
1174+ output artifacts for a package. By using `--mappings-onlys`, Lake will only
1175+ download the mappings abd delay downloading artifacts until they are needed.
11721176
11731177If a download for an artifact fails or the download process for a whole
11741178package fails, Lake will report this and continue on to the next. Once done,
11751179if any download failed, Lake will exit with a nonzero status code.
11761180```
11771181
1178- :::lake cache get "[mappings] [\" --max-revs=\" cn] [\" --rev=\" «commit-hash»] [\" --service=\" «name»] [\" --repo=\" «github-repo»] [\" --platform=\" «target-triple»] [\" --toolchain=\" «name»] [\" --scope=\" «remote-scope»] [\" --download-arts \" ] [\" --force-download\" ]"
1182+ :::lake cache get "[mappings] [\" --max-revs=\" cn] [\" --rev=\" «commit-hash»] [\" --service=\" «name»] [\" --repo=\" «github-repo»] [\" --platform=\" «target-triple»] [\" --toolchain=\" «name»] [\" --scope=\" «remote-scope»] [\" --mappings-only \" ] [\" --force-download\" ]"
11791183Downloads build outputs for packages in the workspace from a remote cache service to the local Lake {tech (key:="local cache" )}[artifact cache].
11801184The cache service used can be specified via the {lakeOpt}`--service` option.
11811185Otherwise, Lake will use the system default, or, if none is configured, Reservoir.
@@ -1195,9 +1199,8 @@ Lake will download the artifacts for the most recent commit with available mappi
11951199It will backtrack up to {lakeOptDef option}`--max-revs`, which defaults to 100.
11961200If set to 0 , Lake will search the repository's whole history, or as far back as Git will allow.
11971201
1198- With a named service and without a mappings file, Lake will only download the input-to-output mappings for packages.
1199- It will delay downloading of the corresponding artifacts to the next `lake build` that requires them.
1200- Using {lakeOptDef option}`--download-arts` will force Lake to download all artifacts eagerly.
1202+ By default, Lake will download both the input-to-output mappings and the output artifacts for packages.
1203+ Using {lakeOptDef option}`--mappings-only` will cause Lake to only download the mappings and delay downloading artifacts until they are needed.
12011204Using {lakeOptDef option}`--force-download` will redownload existing files.
12021205
12031206While downloading, Lake will continue on when a download for an artifact fails or if the download process for a whole package fails.
@@ -1213,7 +1216,7 @@ USAGE:
12131216
12141217Uploads the input-to-output mappings contained in the specified file along
12151218with the corresponding output artifacts to a remote cache. The cache service
1216- used via be specified via `--service` option. If not specifed , Lake will used
1219+ used can be specified via the `--service` option. If not specified , Lake will use
12171220the system default, or error if none is configured. See the help page of
12181221`lake cache services` for more information on how to configure services.
12191222
@@ -1282,7 +1285,7 @@ As such, the command will warn if the work tree currently has changes.
12821285::::
12831286
12841287```lakeCacheHelp add
1285- Addd input-to-output mappings to the Lake cache
1288+ Add input-to-output mappings to the Lake cache
12861289
12871290USAGE:
12881291 lake cache add <mappings>
@@ -1377,6 +1380,70 @@ If no `cache.defaultService` is configured, Lake will use Reservoir by default.
13771380:::
13781381::::
13791382
1383+ ```lakeCacheHelp stage
1384+ Copy build outputs from the cache to a staging directory
1385+
1386+ USAGE:
1387+ lake cache stage <mappings> <staging-directory>
1388+
1389+ Creates the staging directory and copies the mappings file to it. Then, it
1390+ copies all artifacts described within the mappings file from the cache to the
1391+ staging directory. Errors if any of the artifacts described cannot be found in
1392+ the cache.
1393+ ```
1394+
1395+ ::::lake cache stage "mappings «staging-directory»"
1396+ Creates {lakeMeta}`staging-directory` and copies the {lakeMeta}`mappings` file to it.
1397+ After this, it copies all artifacts described within the mappings file from the cache to the
1398+ staging directory.
1399+ It is an error if any of the artifacts described cannot be found in the cache.
1400+ ::::
1401+
1402+ ```lakeCacheHelp unstage
1403+ Cache build outputs from a staging directory
1404+
1405+ USAGE:
1406+ lake cache unstage <staging-directory>
1407+
1408+ Copies the mappings and artifacts stored in staging directory (e.g., via
1409+ `lake cache stage`) back into the cache.
1410+
1411+ Reads the mappings file located at `outputs.jsonl` within the staging
1412+ directory and writes the mappings to the Lake cache. Then, it copies the
1413+ described artifacts from the staging directory into the cache.
1414+ ```
1415+
1416+ ::::lake cache unstage "«staging-directory»"
1417+
1418+ Copies the mappings and artifacts stored in {lakeMeta}`staging-directory` (e.g., via {lake}`cache stage`) back into the cache.
1419+
1420+ Reads the mappings file located at `outputs.jsonl` within the staging
1421+ directory and writes the mappings to the Lake cache. Then, it copies the
1422+ described artifacts from the staging directory into the cache.
1423+ ::::
1424+
1425+
1426+ ```lakeCacheHelp "put-stage"
1427+ Manage the Lake cache
1428+
1429+ USAGE:
1430+ lake cache <COMMAND>
1431+
1432+ COMMANDS:
1433+ get [<mappings>] download build outputs into the local Lake cache
1434+ put <mappings> upload build ouptuts to a remote cache
1435+ add <mappings> add input-to-output mappings to the Lake cache
1436+ clean removes ALL froms the local Lake cache
1437+ services print configured remote cache services
1438+
1439+ STAGING COMMANDS:
1440+ stage <map> <dir> copy build outputs from the cache to a directory
1441+ unstage <dir> cache build outputs from a staging directory
1442+ put-staged <dir> upload build outputs from a staging directory
1443+
1444+ See `lake cache help <command>` for more information on a specific command.
1445+ ```
1446+
13801447
13811448# Configuration Files
13821449
0 commit comments