zip --symlinks and -y: Store Symlinks
zip -y (also written --symlinks) stores symbolic links as symlinks rather than archiving the file they point to.
By default zip follows symlinks and stores the target file. When the link itself matters, -y preserves it as a link.
What it does
Without -y, zip dereferences a symbolic link and stores a copy of the target file under the link name. With -y (--symlinks), zip records the symlink itself, so extraction recreates the link. This only applies on systems that support symlinks.
Common usage
# store symlinks as links, not their targets
zip -y -r bundle.zip dist
# default behavior follows links and stores target contents
zip -r bundle.zip distOptions
| Flag | What it does |
|---|---|
| -y / --symlinks | Store symbolic links instead of following them |
| -r | Recurse into directories |
| -q | Quiet output |
| -X | Exclude extra attributes |
In CI
node_modules and some build trees contain symlinks. If you archive without -y, the link targets get duplicated, inflating the archive and possibly breaking expected link relationships on extraction. If you do want the real file contents (for example shipping a self-contained bundle), the default follow behavior is correct. Decide based on whether the consumer needs links or files.
Common errors in CI
A surprisingly large archive often comes from zip following symlinks and storing duplicate target contents; add -y to store links instead. On extraction, unzip recreates symlinks only on systems that support them and may warn on platforms that do not. A symlink pointing outside the tree, when followed, can pull in unexpected files.