unzip -j and -x: Flatten and Selective Extract
unzip -j extracts files flat by base name, unzip -x excludes matching entries, and naming paths extracts only those.
You do not always need the whole archive or its folder layout. unzip can flatten the tree, pull just the paths you ask for, or extract everything except a pattern.
What it does
unzip -j ignores the directory paths stored in the archive and writes each file into the extraction directory by its base name only, creating no subdirectories. unzip archive.zip <files> extracts only the named entries or patterns, while unzip archive.zip -x <pattern> extracts everything except matches. Patterns use shell-style wildcards interpreted by unzip, so quote them.
Common usage
# flatten all files into ./out, overwriting
unzip -j -o artifact.zip -d ./out
# extract only the dist tree
unzip artifact.zip 'dist/*' -d ./out
# extract everything except tests
unzip artifact.zip -x '*/test/*' -d ./outOptions
| Flag | What it does |
|---|---|
| -j | Junk paths, extract files flat by base name |
| <pattern> | Extract only entries matching the pattern |
| -x <pattern> | Exclude entries matching the pattern |
| -d <dir> | Target directory |
| -o | Overwrite without prompting |
In CI
Selective extraction saves time and disk when an archive is large but you need only part of it, for example pulling just the dist tree out of a full build artifact. Quote patterns so unzip, not the shell, does the matching, since unzip wildcards match across slashes. With -j, if two entries share a base name the second overwrites the first, so add -o and verify the file count when collisions are possible.
Common errors in CI
"caution: filename not matched: <pattern>" means the include or exclude pattern matched nothing; check the stored paths with unzip -l. An unquoted pattern may be expanded by the shell before unzip sees it. With -j, silent data loss from base-name collisions is the main hazard: fewer files land than the archive contains, with no error, and without -o the collision triggers the "replace?" prompt that hangs the job. Do not flatten a deployment package, since -j discards a layout the runtime requires.