doc: clarify that tgz takeout archives must be extracted before import - #1389
Open
luke3butler wants to merge 2 commits into
Open
luke3butler wants to merge 2 commits into
luke3butler wants to merge 2 commits into
Conversation
best-practices.md implied tgz archives were importable; parseArgs.go rejects .tgz/.tar.gz. Recommend zip, and tell tgz users to extract all parts into one folder tree first.
Passing each extracted part folder works: the takeout adapter merges all path arguments into one catalog keyed by relative path. What breaks matching is passing the parts' parent directory, or importing parts in separate runs.
|
Great docs improvement. It may help to include an explicit warning snippet for users when tgz archives are not extracted. |
BeLazy167
added a commit
to BeLazy167/immich-go
that referenced
this pull request
Sep 13, 2026
immich-go rejects .tgz/.tar.gz Google Takeout parts by design (gzip streams cannot be seeked, see simulot#36, simulot#96, simulot#1038), but the error only said the archive can't be used. Users hit this after downloading hundreds of GB and are left guessing. Say what to do: extract all parts into one folder and pass the folder, or re-export as ZIP. Complements simulot#1389 (docs).
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The docs imply tgz takeouts import directly —
best-practices.mdwarns "Don't mix ZIP and TGZ formats in the same import" — butinternal/fshelper/parseArgs.gorejects.tgz/.tar.gzwithimmich-go can't use tgz archives.This updates the docs to match the code:
docs/best-practices.md: replace the mixed-formats bullet with guidance to prefer ZIP, and to extract TGZ takeouts (all parts into one folder tree) before importingdocs/commands/upload.md: add the same note underfrom-google-photosusageRelated: #36 (original tgz request), #1387 (error accumulation in the same code path).