diff --git a/docs-website/static/docs/tutorials/differential_package_create.html b/docs-website/static/docs/tutorials/differential_package_create.html
new file mode 100644
index 0000000000..abd1f4d896
--- /dev/null
+++ b/docs-website/static/docs/tutorials/differential_package_create.html
@@ -0,0 +1,157 @@
+
+
+
+
+
+
+
+
+$ cd examples/longhorn
+$ zarf package create . --confirm
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-05-19-09-17-38-3093453865.log
+
+Using build directory .
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+kind: ZarfPackageConfig
+metadata:
+ name: longhorn
+ description: Example package for Longhorn cloud native distributed block storage for Kubernetes
+ version: 1.4.0
+components:
+- name: longhorn-environment-check
+ required: true
+ actions:
+ onDeploy:
+ after:
+ - cmd: |
+ export PATH=$PATH:./
+ awk '{gsub(/kubectl /, "./zarf tools kubectl ")} 1' ./environment_check.sh > tmp && mv tmp ./environment_check.sh
+ awk '{gsub(/"kubectl" /, "")} 1' ./environment_check.sh > tmp && mv tmp ./environment_check.sh
+ chmod +x ./environment_check.sh
+ ./environment_check.sh
+ files:
+ - source: https://raw.githubusercontent.com/longhorn/longhorn/v1.4.0/scripts/environment_check.sh
+ target: environment_check.sh
+ executable: true
+ - source: https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64
+ target: jq
+ executable: true
+- name: longhorn
+ description: Deploy Longhorn into a Kubernetes cluster. https://longhorn.io
+ required: true
+ actions:
+ onRemove:
+ before:
+ - cmd: "./zarf tools kubectl -n longhorn-system patch -p '{\"value\": \"true\"}' --type=merge lhs deleting-confirmation-flag"
+ charts:
+ - name: longhorn
+ url: https://charts.longhorn.io
+ version: 1.4.0
+ namespace: longhorn-system
+ valuesFiles:
+ - values.yaml
+ manifests:
+ - name: longhorn-connect
+ namespace: longhorn-system
+ files:
+ - connect.yaml
+ images:
+ - longhornio/csi-attacher:v3.4.0
+ - longhornio/csi-provisioner:v2.1.2
+ - longhornio/csi-resizer:v1.3.0
+ - longhornio/csi-snapshotter:v5.0.1
+ - longhornio/csi-node-driver-registrar:v2.5.0
+ - longhornio/livenessprobe:v2.8.0
+ - longhornio/backing-image-manager:v1.4.0
+ - longhornio/longhorn-engine:v1.4.0
+ - longhornio/longhorn-instance-manager:v1.4.0
+ - longhornio/longhorn-manager:v1.4.0
+ - longhornio/longhorn-share-manager:v1.4.0
+ - longhornio/longhorn-ui:v1.4.0
+ - longhornio/support-bundle-kit:v0.0.17
+ ✔ Create Zarf package confirmed
+
+
+
+ 📦 LONGHORN-ENVIRONMENT-CHECK COMPONENT
+
+
+
+ • Downloading environment_check.sh
+ ✔ Downloaded https://raw.githubusercontent.com/longhorn/longhorn/v1.4.0/scripts/environment_check.sh
+ • Downloading jq-linux64
+ ✔ Downloaded https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64
+
+
+
+ 📦 LONGHORN COMPONENT
+
+
+
+ • Processing helm chart longhorn:1.4.0 from repo https://charts.longhorn.io
+ • Processing helm chart longhorn:1.4.0 from repo https://charts.longhorn.io
+ • Loading 1 K8s manifests
+ • Loading 1 K8s manifests
+
+
+
+ 📦 COMPONENT IMAGES
+
+
+
+
+ • Loading metadata for 13 images. This step may take several seconds to complete.
+ • Loading metadata for 13 images. This step may take several seconds to complete.
+ • Pulling Zarf package data (0.00 Byte of 786.66 MBs)
+ ✔ Pulling 13 images (786.66 MBs)
+ • Creating SBOMs for 13 images and 1 components with files.
+ • Creating SBOMs for 13 images and 1 components with files.
+
+
+
diff --git a/docs-website/static/docs/tutorials/differential_package_create_conclusion.html b/docs-website/static/docs/tutorials/differential_package_create_conclusion.html
new file mode 100644
index 0000000000..35d508eff3
--- /dev/null
+++ b/docs-website/static/docs/tutorials/differential_package_create_conclusion.html
@@ -0,0 +1,167 @@
+
+
+
+
+
+
+
+
+$ zarf package create . --confirm
+
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-05-19-10-06-38-4201820931.log
+
+Using build directory .
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+kind: ZarfPackageConfig
+metadata:
+ name: longhorn
+ description: Example package for Longhorn cloud native distributed block storage for Kubernetes
+ version: 1.4.2
+components:
+- name: longhorn-environment-check
+ required: true
+ actions:
+ onDeploy:
+ after:
+ - cmd: |
+ export PATH=$PATH:./
+ awk '{gsub(/kubectl /, "./zarf tools kubectl ")} 1' ./environment_check.sh > tmp && mv tmp ./environment_check.sh
+ awk '{gsub(/"kubectl" /, "")} 1' ./environment_check.sh > tmp && mv tmp ./environment_check.sh
+ chmod +x ./environment_check.sh
+ ./environment_check.sh
+ files:
+ - source: https://raw.githubusercontent.com/longhorn/longhorn/v1.4.2/scripts/environment_check.sh
+ target: environment_check.sh
+ executable: true
+ - source: https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64
+ target: jq
+ executable: true
+- name: longhorn
+ description: Deploy Longhorn into a Kubernetes cluster. https://longhorn.io
+ required: true
+ actions:
+ onRemove:
+ before:
+ - cmd: "./zarf tools kubectl -n longhorn-system patch -p '{\"value\": \"true\"}' --type=merge lhs deleting-confirmation-flag"
+ charts:
+ - name: longhorn
+ url: https://charts.longhorn.io
+ version: 1.4.2
+ namespace: longhorn-system
+ valuesFiles:
+ - values.yaml
+ manifests:
+ - name: longhorn-connect
+ namespace: longhorn-system
+ files:
+ - connect.yaml
+ images:
+ - longhornio/csi-attacher:v3.4.0
+ - longhornio/csi-provisioner:v2.1.2
+ - longhornio/csi-resizer:v1.3.0
+ - longhornio/csi-snapshotter:v5.0.1
+ - longhornio/csi-node-driver-registrar:v2.5.0
+ - longhornio/livenessprobe:v2.8.0
+ - longhornio/backing-image-manager:v1.4.2
+ - longhornio/longhorn-engine:v1.4.2
+ - longhornio/longhorn-instance-manager:v1.4.2
+ - longhornio/longhorn-manager:v1.4.2
+ - longhornio/longhorn-share-manager:v1.4.2
+ - longhornio/longhorn-ui:v1.4.2
+ - longhornio/support-bundle-kit:v0.0.17
+ ✔ Create Zarf package confirmed
+
+
+
+ 📦 LONGHORN-ENVIRONMENT-CHECK COMPONENT
+
+
+
+
+ • Downloading environment_check.sh
+ ✔ Downloaded https://raw.githubusercontent.com/longhorn/longhorn/v1.4.2/scripts/environment_check.sh
+ • Downloading jq-linux64
+ ✔ Downloaded https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64
+
+
+
+ 📦 LONGHORN COMPONENT
+
+
+
+
+ • Processing helm chart longhorn:1.4.2 from repo https://charts.longhorn.io
+ • Processing helm chart longhorn:1.4.2 from repo https://charts.longhorn.io
+ • Loading 1 K8s manifests
+ • Loading 1 K8s manifests
+
+
+
+ 📦 COMPONENT IMAGES
+
+
+
+
+ • Loading metadata for 13 images. This step may take several seconds to complete.
+ • Loading metadata for 13 images. This step may take several seconds to complete.
+ • Pulling Zarf package data (0.00 Byte of 786.07 MBs)
+ ✔ Pulling 13 images (786.07 MBs)
+ • Creating SBOMs for 13 images and 1 components with files.
+ • Creating SBOMs for 13 images and 1 components with files.
+
+
+$ ls -alh *.tar.zst
+
+-rw-r--r-- 1 jason staff 582M May 19 10:06 zarf-package-longhorn-arm64-1.4.0-differential-1.4.2.tar.zst
+-rw-r--r-- 1 jason staff 759M May 19 09:18 zarf-package-longhorn-arm64-1.4.0.tar.zst
+-rw-r--r-- 1 jason staff 760M May 19 10:07 zarf-package-longhorn-arm64-1.4.2.tar.zst
+
+
+
+
diff --git a/docs-website/static/docs/tutorials/differential_package_create_differential.html b/docs-website/static/docs/tutorials/differential_package_create_differential.html
new file mode 100644
index 0000000000..aee66ef5be
--- /dev/null
+++ b/docs-website/static/docs/tutorials/differential_package_create_differential.html
@@ -0,0 +1,152 @@
+
+
+
+
+
+
+
+
+$ zarf package create . --confirm --differential ./zarf-package-longhorn-arm64-1.4.0.tar.zst
+
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-05-19-10-05-47-1789559558.log
+
+Using build directory .
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+kind: ZarfPackageConfig
+metadata:
+ name: longhorn
+ description: Example package for Longhorn cloud native distributed block storage for Kubernetes
+ version: 1.4.2
+components:
+- name: longhorn-environment-check
+ required: true
+ actions:
+ onDeploy:
+ after:
+ - cmd: |
+ export PATH=$PATH:./
+ awk '{gsub(/kubectl /, "./zarf tools kubectl ")} 1' ./environment_check.sh > tmp && mv tmp ./environment_check.sh
+ awk '{gsub(/"kubectl" /, "")} 1' ./environment_check.sh > tmp && mv tmp ./environment_check.sh
+ chmod +x ./environment_check.sh
+ ./environment_check.sh
+ files:
+ - source: https://raw.githubusercontent.com/longhorn/longhorn/v1.4.2/scripts/environment_check.sh
+ target: environment_check.sh
+ executable: true
+ - source: https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64
+ target: jq
+ executable: true
+- name: longhorn
+ description: Deploy Longhorn into a Kubernetes cluster. https://longhorn.io
+ required: true
+ actions:
+ onRemove:
+ before:
+ - cmd: "./zarf tools kubectl -n longhorn-system patch -p '{\"value\": \"true\"}' --type=merge lhs deleting-confirmation-flag"
+ charts:
+ - name: longhorn
+ url: https://charts.longhorn.io
+ version: 1.4.2
+ namespace: longhorn-system
+ valuesFiles:
+ - values.yaml
+ manifests:
+ - name: longhorn-connect
+ namespace: longhorn-system
+ files:
+ - connect.yaml
+ images:
+ - longhornio/backing-image-manager:v1.4.2
+ - longhornio/longhorn-engine:v1.4.2
+ - longhornio/longhorn-instance-manager:v1.4.2
+ - longhornio/longhorn-manager:v1.4.2
+ - longhornio/longhorn-share-manager:v1.4.2
+ - longhornio/longhorn-ui:v1.4.2
+ ✔ Create Zarf package confirmed
+
+
+
+ 📦 LONGHORN-ENVIRONMENT-CHECK COMPONENT
+
+
+
+
+ • Downloading environment_check.sh
+ ✔ Downloaded https://raw.githubusercontent.com/longhorn/longhorn/v1.4.2/scripts/environment_check.sh
+ • Downloading jq-linux64
+ ✔ Downloaded https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64
+
+
+
+ 📦 LONGHORN COMPONENT
+
+
+
+
+ • Processing helm chart longhorn:1.4.2 from repo https://charts.longhorn.io
+ • Processing helm chart longhorn:1.4.2 from repo https://charts.longhorn.io
+ • Loading 1 K8s manifests
+ • Loading 1 K8s manifests
+
+
+
+ 📦 COMPONENT IMAGES
+
+
+
+
+ • Loading metadata for 6 images. This step may take several seconds to complete.
+ • Loading metadata for 6 images. This step may take several seconds to complete.
+ • Pulling Zarf package data (0.00 Byte of 600.86 MBs)
+ ✔ Pulling 6 images (600.86 MBs)
+ • Creating SBOMs for 6 images and 1 components with files.
+ • Creating SBOMs for 6 images and 1 components with files.
+
+
+
diff --git a/docs-website/static/docs/tutorials/differential_package_edit.html b/docs-website/static/docs/tutorials/differential_package_edit.html
new file mode 100644
index 0000000000..a6393041c1
--- /dev/null
+++ b/docs-website/static/docs/tutorials/differential_package_edit.html
@@ -0,0 +1,116 @@
+
+
+
+
+
+
+
+
+$ mv zarf.yaml zarf_old.yaml
+$ sed 's/1.4.0/1.4.2/' zarf_old.yaml > zarf.yaml
+$ cat zarf.yaml
+
+kind: ZarfPackageConfig
+metadata:
+ name: longhorn
+ description: "Example package for Longhorn cloud native distributed block storage for Kubernetes"
+ version: "1.4.2"
+components:
+ - name: longhorn-environment-check
+ required: true
+ files:
+ - source: https://raw.githubusercontent.com/longhorn/longhorn/v1.4.2/scripts/environment_check.sh
+ target: environment_check.sh
+ executable: true
+ - source: https://github.com/stedolan/jq/releases/download/jq-1.6/jq-linux64
+ target: jq
+ executable: true
+ actions:
+ # Run the Longhorn Environment Check on this cluster's nodes.
+ onDeploy:
+ after:
+ - cmd: |
+ export PATH=$PATH:./
+ awk '{gsub(/kubectl /, "./zarf tools kubectl ")} 1' ./environment_check.sh > tmp && mv tmp ./environment_check.sh
+ awk '{gsub(/"kubectl" /, "")} 1' ./environment_check.sh > tmp && mv tmp ./environment_check.sh
+ chmod +x ./environment_check.sh
+ ./environment_check.sh
+ - name: longhorn
+ required: true
+ description: "Deploy Longhorn into a Kubernetes cluster. https://longhorn.io"
+ actions:
+ # Set the delete confirmation flag for Longhorn
+ onRemove:
+ before:
+ - cmd: "./zarf tools kubectl -n longhorn-system patch -p '{\"value\": \"true\"}' --type=merge lhs deleting-confirmation-flag"
+ manifests:
+ - name: longhorn-connect
+ namespace: longhorn-system
+ files:
+ - connect.yaml
+ charts:
+ - name: longhorn
+ url: https://charts.longhorn.io
+ version: 1.4.2
+ namespace: longhorn-system
+ valuesFiles:
+ - "values.yaml"
+ images:
+ - longhornio/csi-attacher:v3.4.0
+ - longhornio/csi-provisioner:v2.1.2
+ - longhornio/csi-resizer:v1.3.0
+ - longhornio/csi-snapshotter:v5.0.1
+ - longhornio/csi-node-driver-registrar:v2.5.0
+ - longhornio/livenessprobe:v2.8.0
+ - longhornio/backing-image-manager:v1.4.2
+ - longhornio/longhorn-engine:v1.4.2
+ - longhornio/longhorn-instance-manager:v1.4.2
+ - longhornio/longhorn-manager:v1.4.2
+ - longhornio/longhorn-share-manager:v1.4.2
+ - longhornio/longhorn-ui:v1.4.2
+ - longhornio/support-bundle-kit:v0.0.17
+
+
+
diff --git a/docs-website/static/docs/tutorials/differential_package_error.html b/docs-website/static/docs/tutorials/differential_package_error.html
new file mode 100644
index 0000000000..ec4b1a3579
--- /dev/null
+++ b/docs-website/static/docs/tutorials/differential_package_error.html
@@ -0,0 +1,61 @@
+
+
+
+
+
+
+
+
+$ zarf package create . --confirm --no-progress --differential ./zarf-package-longhorn-arm64-1.4.0.tar.zst
+
+Saving log file to
+/var/folders/bk/rz1xx2sd5zn134c0_j1s2n5r0000gp/T/zarf-2023-05-19-09-30-01-3248364459.log
+
+Using build directory .
+ ERROR: Failed to create package: unable to create a differential package with the same version as the
+ package you are using as a reference; the package version must be incremented
+
+
+
diff --git a/docs/.images/tutorials/differential_package_thumbnail.png b/docs/.images/tutorials/differential_package_thumbnail.png
new file mode 100644
index 0000000000..d62413d372
Binary files /dev/null and b/docs/.images/tutorials/differential_package_thumbnail.png differ
diff --git a/docs/5-zarf-tutorials/10-package-create-differential.md b/docs/5-zarf-tutorials/10-package-create-differential.md
new file mode 100644
index 0000000000..c8a94b94fb
--- /dev/null
+++ b/docs/5-zarf-tutorials/10-package-create-differential.md
@@ -0,0 +1,58 @@
+# Differential Packages with Zarf
+
+## Introduction
+
+In this tutorial, you will create a differential package using Zarf. This is useful when deploying updates to a package that shares common git repositories and container images across versions. Differential packages only pack what has changed, ensuring that those resources will only need to be packaged and deployed once.
+
+## System Requirements
+
+- Internet access to download resources or upload packages
+- Access to a registry (this tutorial uses Docker Hub)
+
+## Prerequisites
+
+For following along locally, please ensure the following prerequisites are met:
+
+- Zarf binary installed on your `$PATH`: ([Installing Zarf](../1-getting-started/index.md#installing-zarf))
+- The [Zarf](https://github.com/defenseunicorns/zarf) repository cloned: ([`git clone` Instructions](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository))
+
+## Youtube Tutorial
+[](https://youtu.be/6yQEo4Vhz9o "Create Differential Packages with Zarf")
+
+## Create a Differential Package
+In this example we're going to use the [Longhorn Example](../../examples/longhorn/) to create a differential package.
+
+:::note
+
+You'll notice we're not using a cluster in this example. That's because differential packages only affect package creation and do not require a running cluster to make.
+
+:::
+
+1. From the `examples/longhorn` folder, Create the Zarf package with the `zarf package create` command.
+
+
+
+2. Modify the `zarf.yaml` file to upgrade all of the 1.4.0 images to version 1.4.2; leave everything else the same.
+
+3. Update the version of the package as well in the [metadata.version](/docs/create-a-zarf-package/zarf-schema#metadata) field.
+
+:::caution
+
+Creating differential packages without updating the package version will result in an error.
+
+
+
+:::
+
+
+
+4. Next, use the `zarf package create` command with the `--differential` flag to specify a reference package. This will build the differential package omitting the images, repositories, and OCI skeleton components that are already present in the specified Zarf package and are pinned to a specific version/shasum.
+
+
+
+## Conclusion
+
+You have now learned to create differential packages with Zarf. If you would like to see the size you saved, you can use the `zarf package create` command without the `--differential` flag. You'll notice a size difference between the two packages since the differential package omits duplicate contents.
+
+
+
diff --git a/examples/longhorn/zarf.yaml b/examples/longhorn/zarf.yaml
index 5f6cdbbaaa..129ef33123 100644
--- a/examples/longhorn/zarf.yaml
+++ b/examples/longhorn/zarf.yaml
@@ -2,6 +2,7 @@ kind: ZarfPackageConfig
metadata:
name: longhorn
description: Example package for Longhorn cloud native distributed block storage for Kubernetes
+ version: 1.4.0
components:
- name: longhorn-environment-check
required: true