Document repository archive file structure
Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.
Problem to solve
The directory structure format used in the generated project repository archives retrieved by the API is not documented as a stable behavior in the API docs.
Further details
The Repository API provides a way to retrieve archives of any project:
GET /projects/:id/repository/archive[.format]These can be downloaded in multiple formats (TAR.GZ, ZIP) and carry contents of a git-archive command run over the repository under a specific prefix structure.
For ex. requesting a branch name nests the content within a directory prefix named project-branch-fullsha/. (Test with:)
curl -o foo.zip https://gitlab.com/api/v4/projects/gitlab-org%2Fgitlab/repository/archive?sha=master
unzip -l foo.zip | head -10While requesting a direct SHA nests it under project-sha-fullsha/. (Test with:)
curl -o foo.zip https://gitlab.com/api/v4/projects/gitlab-org%2Fgitlab/repository/archive?sha=d27e4995814015252391c488d082d96935497e29
unzip -l foo.zip | head -10(Short SHAs are also accepted, generating project-shortsha-fullsha)
This prefix generating behavior, while asserted in tests in the code, is not documented as an expected or stable behavior to users of the API that would end up relying on it.
Proposal
We should document the various forms of prefixes one can expect when using this API.
Who can address the issue
The developers maintaining the archive_prefix method inside lib/gitlab/git/repository.rb file should be able to vouch for the stability of the naming format. I couldn't find a direct codeowner map for that file or its immediate parent, but the Source Code group may be the right one.