GitLabgitlab-org
cli
main
1//go:build linux || darwin
3package dockercredhelper
5import (
6 "errors"
7 "fmt"
8 "io/fs"
9 "os"
10 "path/filepath"
11 "slices"
12 "strings"
13 "syscall"
15 "gitlab.com/gitlab-org/cli/internal/fsx"
16)
18// Supported reports whether this operating system can run the shim. It always
19// succeeds here.
20func Supported() error { return nil }
22// candidate is a directory Install may write the shim into.
23type candidate struct {
24 dir string
25 // onPath records whether Docker can resolve the shim from dir as things
26 // stand. Only ~/.local/bin can be false: every other candidate is a PATH
27 // entry.
28 onPath bool
29 // create is set only for ~/.local/bin. A PATH entry that does not exist
30 // is not somewhere the user asked glab to put files, whereas ~/.local/bin
31 // is the conventional per-user bin directory and creating it is expected.
32 create bool
33}
35// candidates returns the directories Install tries, in order. glabDir is the
36// directory holding the glab binary.
37//
38// The shim re-resolves glab from PATH at run time rather than calling it by
39// absolute path, so it does not have to sit next to the binary. The one hard
40// requirement is a directory on PATH, because that is how Docker finds it.
41//
42// A failure to resolve the home directory is returned rather than fatal: it
43// costs only the ~/.local/bin candidate, and a writable PATH entry still
44// gives a working install. Install folds it into its own error if nothing
45// else works out, where an unset $HOME is the actionable part.
46func candidates(glabDir string) ([]candidate, error) {
47 // Cleaned once, so membership and dedup compare the same spelling: a PATH
48 // holding both /usr/bin and /usr/bin/ is one directory, and treating it as
49 // two attempts the same write twice and names it twice in the failure.
50 var onPath []string
51 seen := make(map[string]struct{})
52 for _, entry := range filepath.SplitList(os.Getenv("PATH")) {
53 // Relative entries are skipped rather than resolved: "" means the
54 // working directory, so honoring one would put the shim wherever glab
55 // happened to be run from and leave Docker resolving it only from
56 // there.
57 if filepath.IsAbs(entry) {
58 onPath = append(onPath, filepath.Clean(entry))
59 }
60 }
62 var localBin string
63 home, homeErr := os.UserHomeDir()
64 if homeErr != nil {
65 homeErr = fmt.Errorf("resolving the home directory for the %s fallback: %w", FullName, homeErr)
66 } else {
67 localBin = filepath.Join(home, ".local", "bin")
68 }
70 var found []candidate
71 add := func(dir string, create bool) {
72 dir = filepath.Clean(dir)
73 if _, dup := seen[dir]; dup {
74 return
75 }
76 seen[dir] = struct{}{}
77 found = append(found, candidate{dir: dir, onPath: slices.Contains(onPath, dir), create: create})
78 }
80 // glabDir first. Locate resolved glab through PATH, so this directory is on
81 // PATH by construction, and trying it first keeps a writable install
82 // idempotent: the shim already next to glab is updated in place rather than
83 // orphaned behind a second copy elsewhere on PATH.
84 add(glabDir, false)
86 // ~/.local/bin second, whether or not it is on PATH, and ahead of every
87 // other PATH entry. It belongs to this user, where /usr/local/bin and
88 // /opt/homebrew/bin are machine-wide and commonly group-writable. The shim
89 // is written 0700, so a machine-wide copy is executable only by whoever
90 // installed it: a second user's Docker finds it on PATH and fails with
91 // permission denied instead of falling through, and their own
92 // configure-docker then replaces it with a copy the first user cannot run.
93 // A warning the user has to act on beats two users breaking each other.
94 if localBin != "" {
95 add(localBin, true)
96 }
98 // Reached only when neither of the above would accept the write.
99 for _, dir := range onPath {
100 add(dir, false)
101 }
103 return found, homeErr
104}
106// unusable reports whether err means the directory itself will not do, as
107// opposed to something having gone wrong with this particular write. Only the
108// former is worth trying the next candidate for; a full disk or an I/O error
109// would fail identically everywhere, and retrying it down the whole of PATH
110// would bury the real cause under a list of directories.
111func unusable(err error) bool {
112 return errors.Is(err, fs.ErrPermission) ||
113 errors.Is(err, fs.ErrNotExist) ||
114 errors.Is(err, syscall.EROFS) ||
115 errors.Is(err, syscall.ENOTDIR)
116}
118// Install writes the shim into the first directory that will accept it,
119// preferring the one holding the glab binary, and returns where it landed. It
120// is idempotent: re-running it overwrites the script and forces the mode, so a
121// shim left by an older glab is brought up to date.
122//
123// The preference order exists because glab's own directory is frequently not
124// writable by the user running it: /usr/bin under the .deb and .rpm packages,
125// or a read-only Nix store. That used to fail the whole command.
126func Install() (Installation, error) {
127 glabPath, err := Locate()
128 if err != nil {
129 return Installation{}, err
130 }
132 dirs, homeErr := candidates(filepath.Dir(glabPath))
134 var refused []string
135 for _, c := range dirs {
136 path := filepath.Join(c.dir, FullName)
138 err := writeShim(path, c.create)
139 if err == nil {
140 return Installation{Path: path, OnPath: c.onPath}, nil
141 }
142 if !unusable(err) {
143 return Installation{}, fmt.Errorf("writing %s shim to %s: %w", FullName, c.dir, err)
144 }
145 refused = append(refused, c.dir)
146 }
148 // The directories are named because that is the whole remedy: the user
149 // makes one of them writable, or puts a writable one on PATH. homeErr
150 // joins it here and nowhere else: it only matters once every PATH entry
151 // has refused, and then it is the reason ~/.local/bin is missing from the
152 // list the user is being asked to choose from.
153 return Installation{}, errors.Join(fmt.Errorf(
154 "writing %s shim: no directory could be written to, having tried %s",
155 FullName, strings.Join(refused, ", ")), homeErr)
156}
158func writeShim(path string, createDir bool) error {
159 if createDir {
160 if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
161 return err
162 }
163 }
165 // Docker invokes this one path for every registry it delegates to glab, so
166 // the shim is written through fsx.WriteExecutable rather than in place: a
167 // process killed mid-write, or a docker-credential-glab invocation racing
168 // a concurrent install, must never observe a torn or non-executable
169 // script. WriteExecutable lands the file at its final mode as part of the
170 // same atomic rename, so unlike a write followed by a separate Chmod,
171 // there is no window where the shim exists at its final path but isn't
172 // yet executable.
173 return fsx.WriteExecutable(path, script)
174}
Diagnostics6 git calls · 201 ms
CallStatusSizeTime0201 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 KiB3 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=3 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 · 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=32926 git.response.cache=HIT git.response.duration_ms=2 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:0200245 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=245 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=aba319365668a8024052e17001ff1ccb32f32ad1 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=245 git.pkt.payload.max=218 git.sideband.band1.bytes=218 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=218 git.pack.trailer=a79e8c6a1fa5857567b424874e4f19628bc00ab3Open pack map
fetch2002.8 KiB191 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=191 git.response.bytes=2912 git.response.cache=MISS git.response.duration_ms=191 git.fetch.wants=f023cb2f7524445d7997bda5a85b0cd49fd75a63 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=2912 git.pkt.payload.max=2885 git.sideband.band1.bytes=2885 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
- a5e2eb393aa74bc2
- Request
- 4a040b95…
- 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