tar --strip-components: Drop Path Prefixes (CI Errors)
tar --strip-components=N removes N leading directories from each path on extract.
Release tarballs usually wrap everything in a versioned folder like app-1.2.0/. Stripping one component drops that wrapper so files land where you actually want them.
What it does
tar --strip-components=N removes the first N path components from each member name during extraction. A member stored as app-1.2.0/bin/app extracted with --strip-components=1 becomes bin/app. Members with fewer than N components are skipped entirely.
Common usage
tar -xzf app-1.2.0.tar.gz --strip-components=1 -C /opt/app
curl -L url | tar -xz --strip-components=1 -C ./vendor
tar -xzf release.tgz --strip-components=2 path/in/archiveOptions
| Form | What it does |
|---|---|
| --strip-components=N | Remove N leading path components on extract |
| --strip-components=1 | Drop the top-level versioned folder (most common) |
| (combine with -C) | Strip the prefix and redirect the destination |
| BSD: --strip-components | Same flag on macOS bsdtar |
In CI
Installing a downloaded tool is the canonical use: curl -L url | tar -xz --strip-components=1 -C /usr/local pulls bin/tool out of tool-1.2.0/bin/tool and into /usr/local/bin without the version folder, so the binary is on PATH immediately.
Common errors in CI
If extraction produces an empty directory, N was too high: every member had fewer than N components and was silently skipped. Run tar -tzf archive.tgz | head first to count the prefix depth. There is no error message for over-stripping, so verify the result with ls before assuming the install worked.