From: Colin Walters <walters@verbum.org>
Date: Thu, 11 Feb 2021 21:19:18 +0000 (+0000)
Subject: docs: Describe using scratch/empty deltas for initial fetches
X-Git-Tag: archive/raspbian/2022.1-3+rpi1~1^2~4^2~5^2~14^2~2
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=2195a6099b254dcc513e2ee0289eb5d07ad17287;p=ostree.git

docs: Describe using scratch/empty deltas for initial fetches

Came up with a user hitting ratelimiting from S3.
---

diff --git a/docs/repository-management.md b/docs/repository-management.md
index 41b8d2b1..ace150ad 100644
--- a/docs/repository-management.md
+++ b/docs/repository-management.md
@@ -248,5 +248,26 @@ will have "tombstone markers" added so that you know they were
 explicitly deleted, but all content in them (that is not referenced by
 a still retained commit) will be garbage collected.
 
+
+## Generating "scratch" deltas for efficient initial downloads
+
+In general, the happy path for OSTree downloads is via static deltas.
+If you are in a situation where you want to download an OSTree
+commit from an uninitialized repo (or one with unrelated history), you
+can generate "scratch" (aka `--empty` deltas) which bundle all
+objects for that commit.
+
+The tradeoff here is increasing server disk space in return
+for many fewer client HTTP requests.
+
+For example:
+
+```
+$ ostree --repo=/path/to/repo static-delta generate --empty --to=exampleos/x86_64/testing-devel
+$ ostree --repo=/path/to/repo summary -u
+```
+
+After that, clients fetching that commit will prefer fetching the "scratch" delta if they don't have the original ref.
+
 ###### Licensing for this document:
 `SPDX-License-Identifier: (CC-BY-SA-3.0 OR GFDL-1.3-or-later)`