GitLabgitlab-org
cli
main
1package download
3import (
4 "bytes"
5 "context"
6 "crypto/sha256"
7 "encoding/hex"
8 "errors"
9 "fmt"
10 "io"
11 "os"
12 "path/filepath"
14 "github.com/MakeNowJust/heredoc/v2"
15 "github.com/spf13/cobra"
17 gitlab "gitlab.com/gitlab-org/api/client-go/v3"
19 "gitlab.com/gitlab-org/cli/internal/cmdutils"
20 "gitlab.com/gitlab-org/cli/internal/commands/packages/helpers"
21 "gitlab.com/gitlab-org/cli/internal/glrepo"
22 "gitlab.com/gitlab-org/cli/internal/iostreams"
23 "gitlab.com/gitlab-org/cli/internal/mcpannotations"
24 "gitlab.com/gitlab-org/cli/internal/utils"
25)
27type options struct {
28 io *iostreams.IOStreams
29 gitlabClient func() (*gitlab.Client, error)
30 baseRepo func() (glrepo.Interface, error)
32 packageName string
33 packageVersion string
34 fileName string
35 path string
36 verifyChecksum bool
37 forceDownload bool
38}
40func NewCmd(f cmdutils.Factory) *cobra.Command {
41 opts := &options{
42 io: f.IO(),
43 gitlabClient: f.GitLabClient,
44 baseRepo: f.BaseRepo,
45 }
46 cmd := &cobra.Command{
47 Use: "download --name <package> --version <version> --filename <file> [flags]",
48 Short: `Download a file from a project's package registry.`,
49 Long: heredoc.Docf(`
50 Download a generic package file, identified by its package name, version,
51 and file name.
53 Use %[1]s--path%[1]s to choose where the file is saved. If it names a directory
54 (it ends with a separator or already exists as one), the file is saved
55 there under its original name. Otherwise it is saved as that exact path,
56 letting you rename the file. By default the file is saved in the current
57 directory under its original name.
59 By default, the downloaded file is verified against the checksum stored in
60 the registry. This requires extra API calls to look up the file's metadata.
61 Use %[1]s--no-verify%[1]s to skip verification. This can allow corrupted or
62 tampered files; use with caution.
64 If the target file already exists, the download fails. Use %[1]s--force%[1]s to
65 overwrite it.
67 By default, files are downloaded from the current project. Use %[1]s--repo%[1]s
68 to target another project.
69 `, "`"),
70 Example: heredoc.Doc(`
71 # Download a package file to the current directory
72 glab packages download --name my-package --version 1.0.0 --filename app.zip
74 # Download into a directory, keeping the original file name
75 glab packages download -n my-package --version 1.0.0 --filename app.zip --path ./downloads/
77 # Download to an exact path, renaming the file
78 glab packages download -n my-package --version 1.0.0 --filename app.zip --path ./downloads/renamed.zip
80 # Download to an absolute path
81 glab packages download -n my-package --version 1.0.0 --filename app.zip --path /tmp/downloads/app.zip
83 # Download without verifying the checksum
84 glab packages download -n my-package --version 1.0.0 --filename app.zip --no-verify
86 # Overwrite an existing file
87 glab packages download -n my-package --version 1.0.0 --filename app.zip --force
89 # Use the 'dl' alias and target another project
90 glab packages dl -n my-package --version 1.0.0 --filename app.zip -R owner/repo
91 `),
92 Aliases: []string{"dl"},
93 Args: cobra.NoArgs,
94 ValidArgsFunction: cobra.NoFileCompletions,
95 Annotations: map[string]string{
96 mcpannotations.Exclude: "true",
97 },
98 RunE: func(cmd *cobra.Command, args []string) error {
99 if err := opts.complete(cmd); err != nil {
100 return err
101 }
103 return opts.run(cmd.Context())
104 },
105 }
107 fl := cmd.Flags()
108 fl.StringP("name", "n", "", "Name of the package.")
109 fl.String("version", "", "Version of the package.")
110 fl.String("filename", "", "Name of the file within the package to download.")
111 fl.StringP("path", "p", "", "Directory to save the file in (keeps its original name) or a full file path to rename it. Defaults to the original name in the current directory.")
112 fl.Bool("no-verify", false, "Do not verify the checksum of the downloaded file. Warning: when enabled, this setting allows the download of files that are corrupt or tampered with.")
113 fl.Bool("force", false, "Overwrite the target file if it already exists.")
115 cobra.CheckErr(cmd.MarkFlagRequired("name"))
116 cobra.CheckErr(cmd.MarkFlagRequired("version"))
117 cobra.CheckErr(cmd.MarkFlagRequired("filename"))
119 return cmd
120}
122func (o *options) complete(cmd *cobra.Command) error {
123 fl := cmd.Flags()
125 name, err := fl.GetString("name")
126 if err != nil {
127 return err
128 }
129 o.packageName = name
131 version, err := fl.GetString("version")
132 if err != nil {
133 return err
134 }
135 o.packageVersion = version
137 fileName, err := fl.GetString("filename")
138 if err != nil {
139 return err
140 }
141 o.fileName = fileName
143 noVerify, err := fl.GetBool("no-verify")
144 if err != nil {
145 return err
146 }
147 o.verifyChecksum = !noVerify
149 force, err := fl.GetBool("force")
150 if err != nil {
151 return err
152 }
153 o.forceDownload = force
155 path, err := fl.GetString("path")
156 if err != nil {
157 return err
158 }
159 switch {
160 case !fl.Changed("path"):
161 path = o.fileName
162 case isDirectoryPath(path):
163 path = filepath.Join(path, o.fileName)
164 }
165 o.path = filepath.Clean(path)
167 return nil
168}
170// isDirectoryPath reports whether path points at a directory to place the file
171// in, rather than the file's full destination. A trailing separator or an
172// existing directory both signal this, mirroring how `mv` treats its target.
173func isDirectoryPath(path string) bool {
174 if path == "" {
175 return false
176 }
177 if os.IsPathSeparator(path[len(path)-1]) {
178 return true
179 }
180 info, err := os.Stat(path)
181 return err == nil && info.IsDir()
182}
184func (o *options) run(ctx context.Context) (err error) {
185 client, err := o.gitlabClient()
186 if err != nil {
187 return err
188 }
190 repo, err := o.baseRepo()
191 if err != nil {
192 return err
193 }
195 root, name, err := utils.EnsureDestinationRoot(o.path)
196 if err != nil {
197 return err
198 }
199 defer func() { err = errors.Join(err, root.Close()) }()
201 if _, err := root.Stat(name); err == nil && !o.forceDownload {
202 return fmt.Errorf("file %s already exists; use --force to overwrite current file", o.path)
203 }
205 if err := o.saveFile(ctx, client, root, name, repo.FullName()); err != nil {
206 return err
207 }
209 o.io.LogInfof("Downloaded package file to '%s' (Package: %s, Version: %s)\n", o.path, o.packageName, o.packageVersion)
210 return nil
211}
213func (o *options) saveFile(ctx context.Context, client *gitlab.Client, root *os.Root, name, repoName string) (err error) {
214 contents, _, err := client.GenericPackages.DownloadPackageFile(repoName, o.packageName, o.packageVersion, o.fileName, gitlab.WithContext(ctx))
215 if err != nil {
216 return fmt.Errorf("failed to download package file: %w", err)
217 }
219 var expected string
220 if o.verifyChecksum {
221 expected, err = fetchChecksum(ctx, client, repoName, o.packageName, o.packageVersion, o.fileName)
222 if err != nil {
223 return err
224 }
225 }
227 tempFile, err := utils.CreateTemp(root, name)
228 if err != nil {
229 return fmt.Errorf("unable to create temporary file for downloaded package file: %w", err)
230 }
231 // root.OpenFile reports the name joined onto the root, which root's own
232 // methods reject as escaping when the root is absolute. The temporary file
233 // is always a direct child of root, so its base name addresses it.
234 tempName := filepath.Base(tempFile.Name())
236 defer func() {
237 if closeErr := tempFile.Close(); closeErr != nil {
238 err = errors.Join(err, fmt.Errorf("error closing temporary file: %w", closeErr))
239 }
240 if _, statErr := root.Stat(tempName); statErr == nil { // Cleanup the temp file if it hasn't been renamed
241 if removeErr := root.Remove(tempName); removeErr != nil {
242 err = errors.Join(err, fmt.Errorf("error removing temporary file: %w", removeErr))
243 }
244 }
245 }()
247 hasher := sha256.New()
248 var w io.Writer = tempFile
249 if o.verifyChecksum {
250 w = io.MultiWriter(tempFile, hasher)
251 }
253 if _, err := io.Copy(w, bytes.NewReader(contents)); err != nil {
254 return fmt.Errorf("unable to write downloaded file: %w", err)
255 }
257 checksum := hex.EncodeToString(hasher.Sum(nil))
258 if o.verifyChecksum && checksum != expected {
259 return fmt.Errorf("checksum verification failed for %s: expected %s, got %s", o.fileName, expected, checksum)
260 }
262 if err := root.Rename(tempName, name); err != nil {
263 return fmt.Errorf("unable to persist downloaded file contents: %w", err)
264 }
266 return err
267}
269// fetchChecksum looks up the SHA256 stored in the registry for the given file,
270// since DownloadPackageFile returns no metadata. The package is resolved
271// by helpers.GetPackageByName; its files are paginated in case many share the package.
272func fetchChecksum(ctx context.Context, client *gitlab.Client, repoName, name, version, fileName string) (string, error) {
273 pkg, err := helpers.GetPackageByName(ctx, client, name, helpers.DefaultPackageType, version, repoName)
274 if err != nil {
275 return "", fmt.Errorf("failed to look up package: %w", err)
276 }
278 files, err := gitlab.ScanAndCollect(func(p gitlab.PaginationOptionFunc) ([]*gitlab.PackageFile, *gitlab.Response, error) {
279 return client.Packages.ListPackageFiles(repoName, pkg.ID, &gitlab.ListPackageFilesOptions{}, p, gitlab.WithContext(ctx))
280 })
281 if err != nil {
282 return "", fmt.Errorf("failed to look up package files: %w", err)
283 }
285 // A package can hold several files with the same name, because generic
286 // packages accept duplicates by default. The download endpoint serves the
287 // most recent one, so verify against the matching file with the highest ID.
288 var latest *gitlab.PackageFile
289 for _, file := range files {
290 if file.FileName == fileName && (latest == nil || file.ID > latest.ID) {
291 latest = file
292 }
293 }
294 if latest != nil {
295 return latest.FileSHA256, nil
296 }
298 return "", fmt.Errorf("couldn't locate file %s in package %s version %s", fileName, name, version)
299}
Diagnostics8 git calls · 332 ms
CallStatusSizeTime0332 ms
discover200185 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=185 git.server.agent=git/2.56.g1891de4-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=185 git.pkt.payload.max=35
ls-refs20058 KiB2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=59849 git.response.cache=UPDATING git.response.duration_ms=2 git.protocol.version=2 git.pkt.frames=731 git.pkt.data=730 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=59849 git.pkt.payload.max=143 git.ls_refs.count=730 git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=32926 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=22 git.pkt.data=20 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=32926 git.pkt.payload.max=32046 git.sideband.band1.bytes=32046 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=80 git.pack.bytes=32046 git.pack.ofs_delta=36 git.pack.ref_delta=0 git.pack.chain.max=2 git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91 git.pack.full=44Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=4273 git.response.cache=HIT git.response.duration_ms=4 git.fetch.filter=combine:blob:none+tree:2 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=1 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4273 git.pkt.payload.max=4173 git.sideband.band1.bytes=4173 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=11 git.pack.bytes=4173 git.fetch.wide.objects=11 git.fetch.wide.extra_bytes=3930 git.fetch.wide.blobs=0
fetchtree:02001.8 KiB · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=1857 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=1857 git.pkt.payload.max=1830 git.sideband.band1.bytes=1830 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=1830 git.pack.trailer=fb03183b7909876778f740d196d7516811003517Open pack map
fetchtree:0200263 B · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=263 git.response.cache=HIT git.response.duration_ms=4 git.fetch.filter=tree:0 git.fetch.wants=4445ce4c6a6710742ed094287b245091ae79204f git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=263 git.pkt.payload.max=236 git.sideband.band1.bytes=236 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=236 git.pack.trailer=4126ef8ff4c560b52ccdd91c9d0a185a77d21c2dOpen pack map
fetchtree:0200139 B · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=139 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=9ef2aa8df7c241d48da8b281656b7e14f70eaba3 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=139 git.pkt.payload.max=112 git.sideband.band1.bytes=112 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=112 git.pack.trailer=ac014dd502574dc71152e3d20bfead22fb64a2ceOpen pack map
fetch2003.3 KiB317 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=317 git.response.bytes=3340 git.response.cache=MISS git.response.duration_ms=317 git.fetch.wants=3673711273366ad552281accba664568c31af42f git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=3340 git.pkt.payload.max=3313 git.sideband.band1.bytes=3313 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://gitlab.com/gitlab-org/cli
- Ref
- refs/heads/main
- Commit
- 0dd7574dce9e385c5c30540e6c15657adc6bdce9
- cf-ray
- a5e326c8eaff98f1
- Request
- 93e927fe…
- Protocol
- v2 · sha1
- Agent
- git/2.56.g1891de4-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format