Skip to content

Commit 1c76fb6

Browse files
committed
Add delta overview page
1 parent 320169e commit 1c76fb6

File tree

1 file changed

+41
-0
lines changed

1 file changed

+41
-0
lines changed

docs/packaging/deltas.mdx

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Delta Updates
2+
<AppliesTo all />
3+
Delta updates provide speedy updates for even the biggest of applications.
4+
5+
By default, as long as there is a previous release in your `--outputDir` / `-o` directory, Velopack will automatically generate a delta when creating a new release.
6+
7+
:::tip
8+
If you don't have the latest local release, eg. you're running in CI, you can use the `vpk download` command to automatically fetch it so delta's can be created.
9+
:::
10+
11+
Delta packages use [Zstandard](https://github.com/facebook/zstd) to create binary patches of individual files in your package. Due to limitations of Zstandard, no single file can be bigger than 2 GB.
12+
13+
## Optimising for size
14+
The default parameters picked for patch generation are to provide a good balance of size and speed.
15+
If you would like to optimize for size, you can do this with the `--delta BestSize` argument.
16+
YMMV, for some appliations this may give you big size savings, for others it may not. Either way it will be a lot slower, about on-par with the `bsdiff` algorithm.
17+
18+
## How delta's work
19+
During updates, Velopack will look for possibly more than one delta to download. Imagine you have published the following releases:
20+
- `1.0.0`
21+
- `1.0.1`
22+
- `1.0.2`
23+
- `1.0.3`
24+
25+
If a user has not opened your app in a while, and has `1.0.0` installed, the next time they open the app,
26+
3 delta's will be downloaded: `1.0.1-delta`, `1.0.2-delta`, and `1.0.3-delta`.
27+
28+
The previously downloaded/installed package is stored in `%LocalAppData\{packId}\packages`, so Velopack will then apply those 3 delta's sequentially
29+
on top of the local package that exists in that directory.
30+
31+
Once the delta's have been applied, and the `1.0.3` release has been reconstructed, it will be ready for applying.
32+
33+
There is a heuristic in Velopack which will attempt to decide whether it is better to download N delta's or download the latest full release instead.
34+
This is based on a number of factors (eg. size of the full release, sum size of the delta's, total number of delta's between the current & target version).
35+
36+
## GitHub Releases
37+
There is special support for GitHub Releases in `UpdateManager` which will search through a number of previous GitHub Releases for available delta's.
38+
This means any one GitHub release must only have 1 full package and 1 delta update to facilitate proper updating.
39+
40+
## Disabling delta's
41+
If for some reason you don't want to deploy delta's, you can disable them with the `--delta none` argument.

0 commit comments

Comments
 (0)