How to archive merger in developer workflows
- Step 1Gather the artifacts — Download the build/test artifacts you want to combine. Name them meaningfully — the merger uses each filename's stem (extension stripped) to prefix colliding paths, so
build-linux.zipproducesbuild-linux/prefixes. - Step 2Open the Archive Merger — Go to the tool page. Merging is multi-file, so it requires the Pro tier or higher. It runs entirely in the browser, which is why pre-release artifacts are safe to drop.
- Step 3Drop two or more artifacts — Multi-select or drag the archives onto the drop zone. A mix of
.zip,.tar.gz,.tgz,.7z,.rar,.bz2,.xzis fine. A single file is rejected withDrop at least two archives to merge. - Step 4Let formats resolve — fflate reads ZIP/TAR/GZ; libarchive WASM reads 7z/RAR/bz2/xz/ISO. Inputs process in drop order, so put the artifact whose paths you want to keep unprefixed first.
- Step 5Sanity-check the chips — Confirm Entries equals the total files you expected and that the Collisions count makes sense (e.g. one per shared
manifest.jsonacross artifacts). - Step 6Download and attach — Save
merged-N-archives.zipand attach it to the issue, PR, or review. If a system needs tar.gz or 7z, pass it through the archive format converter.
Developer artifact formats and merge behaviour
What common build outputs do when merged. Output is always a single ZIP at fflate level 6.
| Artifact source | Format | Read engine | Merge behaviour |
|---|---|---|---|
| Most CI upload-artifact steps | .zip | fflate (zip.js if encrypted) | Members merged individually; collisions renamed by stem |
| Linux build/test jobs | .tar.gz / .tgz | fflate (gunzip) | Gunzipped as a single stream — may yield one inner file, not expanded members |
| Log captures | .gz | fflate | One file, named from the gzip header or filename minus .gz |
| Third-party tooling | .7z, .rar | libarchive WASM | Read-only; WASM loads on first use |
| Output (always) | .zip | fflate zipSync level 6 | merged-N-archives.zip; no 7z/tar output option |
Capabilities the merger does and does not have
Set expectations before wiring it into a workflow — several common assumptions are false.
| Capability | Available? | Detail |
|---|---|---|
| CLI / API / headless mode | No | Archive tools are interactive browser-only; no end-user automation hook |
| Choose compression level | No | Fixed at fflate level 6; no UI control |
| Password-protect output | No | Use the encrypted ZIP creator for that |
| Reorder inputs after dropping | No | Order is drop order; it decides which copy keeps the bare path |
| Read 7z / RAR / ISO inputs | Yes | Via libarchive WASM, read-only |
| Collision-safe merge | Yes | First writer wins; later duplicates prefixed by stem |
Cookbook
Build-and-review merges with exact output paths, so you can predict the tree before attaching it to a PR.
Multi-platform build merge
Two platform artifacts both carry manifest.json. The first keeps it; the second is prefixed.
Inputs (drop order): build-linux.zip -> bin/app, manifest.json build-windows.zip -> bin/app.exe, manifest.json merged-2-archives.zip: bin/app manifest.json (build-linux — first writer) bin/app.exe build-windows/manifest.json (collision) Chips: Input archives: 2 | Entries: 4 | Collisions: 1
Bundle build + test logs for a bug report
A ZIP build artifact plus a gzipped test log, combined into one attachment.
Inputs: build-artifact.zip -> dist/, coverage/ test-output.gz -> test-output (one file from gunzip) merged-2-archives.zip: dist/... coverage/... test-output Chips: Input archives: 2 | Entries: <N> | Collisions: 0
Forgot the second artifact
The most common slip — dropping a single ZIP.
Input: build-artifact.zip Error: Drop at least two archives to merge. Fix: add the second artifact and re-drop both.
Need a password-protected share
The merger writes plain ZIP. For an encrypted share, build it with the encrypted creator instead, or encrypt the merged output.
Merger output: merged-2-archives.zip (no encryption) For a password: use /archive-tools/encrypted-zip-creator (drop the merged ZIP's contents, set a password, get an AES-256 encrypted ZIP)
Convert merged ZIP to tar.gz for a Linux toolchain
When the destination expects a gzipped tarball, chain the converter.
Step 1: merge build-*.zip -> merged-3-archives.zip Step 2: Archive Format Converter -> merged-3-archives.tar.gz See /archive-tools/archive-format-converter
Edge cases and what actually happens
Expecting a CLI or API
Not availableArchive tools are interactive and browser-only with no end-user API, CLI, or headless mode. The merger cannot be a CI step; use it for hands-on packaging only.
manifest.json collision across artifacts
PreservedNot a failure. The first artifact keeps manifest.json; later copies become <stem>/manifest.json. The Collisions chip counts each, and all survive.
Single artifact dropped
RejectedThe merger throws Drop at least two archives to merge. Add a second input.
tar.gz not expanded into members
By designA .tar.gz is gunzipped as one gzip stream and may contribute a single inner file rather than expanded tar members. Extract the tarball first if you need per-file merging.
Encrypted ZIP artifact
Fails to readNo password is forwarded, so an encrypted input can't be extracted and the merge errors. Decrypt and re-zip first.
Wanting a specific compression level
Not supportedOutput is always fflate level 6 with no control. For tighter compression, post-process with the smart archive compressor.
Drop order matters
By designWhichever artifact is first keeps the bare path on a collision. If the wrong copy ends up prefixed, re-drop with the desired artifact first.
Artifact exceeds tier size/entry cap
RejectedPer-file caps (50 MB Free / 500 MB Pro / 2 GB Pro-media+Developer) and per-archive entry caps apply. Split large artifacts with the archive splitter.
Output must be 7z or tar
Not supportedThe merger writes ZIP only. Convert the result with the format converter, or use a CLI for native 7z/tar output.
Re-merging an already-merged ZIP
SupportedYou can feed merged-N-archives.zip back in with another archive — it's just another ZIP input. Watch for second-round collisions on the already-prefixed paths.
Frequently asked questions
Is there an Archive Merger API or CLI?
No. Archive tools run interactively in the browser with no end-user API, CLI, or headless mode. The merger is for hands-on packaging; for automated merges in CI, script zip/tar in your pipeline.
Can I merge a Linux tar.gz with a Windows zip?
Yes — drop both. The ZIP merges member-by-member; the tar.gz is detected by gzip magic and gunzipped as a single stream, which may contribute one inner file rather than expanded members.
What happens to two manifest.json files?
The first artifact in drop order keeps manifest.json; the second becomes <artifact-stem>/manifest.json. Nothing is overwritten and the Collisions chip counts the rename.
Does drop order matter?
Yes. Inputs are processed in the order you drop them, and the first to claim a path keeps it. Put the artifact whose paths you want unprefixed first.
Can I choose the compression level?
No. The output is always fflate level 6, with no UI control. To compress harder, post-process with the smart archive compressor.
Can I password-protect the merged ZIP?
Not from the merger — it writes plain ZIP. Use the encrypted ZIP creator to produce an AES-256 protected archive instead.
What output format do I get?
Always merged-N-archives.zip (a standard ZIP). For tar.gz or 7z, run it through the archive format converter.
Is anything uploaded? These are pre-release artifacts.
No. All extraction and re-zipping happen in your browser tab — there is no server-side path — so unreleased artifacts stay on your machine.
Will folder structure be preserved?
Yes. Each artifact's internal paths are kept unless they collide, in which case only the later duplicate is prefixed with the artifact stem.
Can I merge more than two artifacts?
Yes — up to 20 on Pro, 100 on Pro-media, unlimited on Developer. The minimum is two.
What if an artifact is corrupt?
The whole merge fails with no partial output. Test the suspect file with the archive integrity tester and exclude it before retrying.
Can I re-merge the output with more archives later?
Yes — the merged ZIP is a normal ZIP and can be an input to another merge. Just be aware that already-prefixed paths can collide again in the second round.
Privacy first
Every JAD Archive tool runs entirely in your browser using fflate, @zip.js/zip.js, and the libarchive WASM bridge. Your archives never leave your device — verified by zero outbound network requests during processing.