website: internals/zstdelta

Summary:
Describe the zstdelta algorithm. It might be interesting to other source
control folks.

Reviewed By: muirdm

Differential Revision: D41275018

fbshipit-source-id: 8e44c3e23716c9130eaaedf751575d37f81e7696

website/docs/internals/zstdelta.md

@@ -0,0 +1,28 @@
+# ZstDelta
+
+ZstDelta uses [zstd](https://www.zstd.net) dictionary compression to calculate
+a compressed delta between two inputs.
+
+## ZstDelta
+
+The `zstdelta` Rust library provides `diff` and `apply` to calculate such
+compressed deltas and restore content from deltas. You can get `delta` from
+`diff(a, b)`, then restore the content of `b` using `apply(a, delta)`.
+
+In Python, `bindings.zstd` provides access to the `diff` and `apply` functions:
+
+```with-output
+>>> import bindings, hashlib
+>>> a = b"".join(hashlib.sha256(str(i).encode()).digest() for i in range(1000))
+>>> len(a)
+>>> b = a[:10000] + b'x' * 10000 + a[11000:]
+>>> diff = bindings.zstd.diff(a, b)
+>>> len(diff)
+>>> bindings.zstd.apply(a, diff) == b
+```
+
+## ZStore
+
+The `zstore` Rust library provides an on-disk content store with internal
+delta-chain management. It uses the above `zstdelta` library for delta
+calculation and IndexedLog for on-disk storage. It is used by MetaLog.

website/src/plugins/sapling-output/src/index.ts

@@ -21,8 +21,15 @@ const EXAMPLE_HEADER = `
   > [ui]
   > color=always
   > EOF
+# hide end
+`
+
+// Compatibility for internal systems where sl is not installed but hg can be
+// used as an alternative.
+const HG_COMPAT_HEADER = `
+# hide begin
   $ sl() {
-  >   hg "$@"
+  >   HGIDENTITY=sl hg "$@"
   > }
 # hide end
 `
@@ -50,7 +57,11 @@ function processInput(text: string): string {
       newLine = `  ${line}`;
     }
     if (firstLine) {
-      newLine = EXAMPLE_HEADER + newLine;
+      let header = EXAMPLE_HEADER;
+      if (!fs.existsSync('/usr/bin/sl')) {
+        header += HG_COMPAT_HEADER;
+      }
+      newLine = header + newLine;
       firstLine = false;
     }
     return newLine;