git: add opt-in command tracing

crazy-max · crazy-max · commit 61ad59f8835a · 2026-03-18T15:03:16.000+01:00
Signed-off-by: CrazyMax &lt;1951866+crazy-max@users.noreply.github.com&gt;
diff --git a/client/llb/git_test.go b/client/llb/git_test.go
@@ -69,6 +69,17 @@ func TestGit(t *testing.T) {
 				"git.fullurl":          "https://github.com/foo/bar.git",
 			},
 		},
+		{
+			name:       "debug commands",
+			st:         Git("github.com/foo/bar.git", "ref", GitDebugCommands()),
+			identifier: "git://github.com/foo/bar.git#ref",
+			attrs: map[string]string{
+				"git.authheadersecret": "GIT_AUTH_HEADER",
+				"git.authtokensecret":  "GIT_AUTH_TOKEN",
+				"git.debugcommands":    "true",
+				"git.fullurl":          "https://github.com/foo/bar.git",
+			},
+		},
 	}
 
 	for _, tc := range tcases {
diff --git a/client/llb/source.go b/client/llb/source.go
@@ -470,11 +470,14 @@ func Git(url, fragment string, opts ...GitOption) State {
 		attrs[pb.AttrGitChecksum] = checksum
 		addCap(&gi.Constraints, pb.CapSourceGitChecksum)
 	}
-
 	if gi.SkipSubmodules {
 		attrs[pb.AttrGitSkipSubmodules] = "true"
 		addCap(&gi.Constraints, pb.CapSourceGitSkipSubmodules)
 	}
+	if gi.DebugCommands {
+		attrs[pb.AttrGitDebugCommands] = "true"
+		addCap(&gi.Constraints, pb.CapSourceGitDebugCommands)
+	}
 
 	addCap(&gi.Constraints, pb.CapSourceGit)
 
@@ -503,6 +506,7 @@ type GitInfo struct {
 	Ref              string
 	SubDir           string
 	SkipSubmodules   bool
+	DebugCommands    bool
 }
 
 func GitRef(v string) GitOption {
@@ -529,6 +533,12 @@ func KeepGitDir() GitOption {
 	})
 }
 
+func GitDebugCommands() GitOption {
+	return gitOptionFunc(func(gi *GitInfo) {
+		gi.DebugCommands = true
+	})
+}
+
 func AuthTokenSecret(v string) GitOption {
 	return gitOptionFunc(func(gi *GitInfo) {
 		gi.AuthTokenSecret = v
diff --git a/frontend/dockerui/build_test.go b/frontend/dockerui/build_test.go
@@ -1,10 +1,14 @@
 package dockerui
 
 import (
+	"context"
 	"testing"
 
 	"github.com/containerd/platforms"
+	"github.com/moby/buildkit/client/llb"
 	"github.com/moby/buildkit/exporter/containerimage/exptypes"
+	"github.com/moby/buildkit/solver/pb"
+	digest "github.com/opencontainers/go-digest"
 	ocispecs "github.com/opencontainers/image-spec/specs-go/v1"
 	"github.com/stretchr/testify/require"
 )
@@ -98,3 +102,65 @@ func TestNormalizePlatform(t *testing.T) {
 		require.Equal(t, platforms.FormatAll(platforms.Normalize(tc.p)), tc.expected.ID)
 	}
 }
+
+func TestDetectGitContextForwardsDebugCommands(t *testing.T) {
+	t.Parallel()
+
+	enabled := true
+	st, ok, err := DetectGitContext("https://github.com/docker/buildx.git?ref=refs/pull/3732/merge", nil, &enabled)
+	require.True(t, ok)
+	require.NoError(t, err)
+
+	g := marshalGitContext(t, st)
+	require.Equal(t, "git://github.com/docker/buildx.git#refs/pull/3732/merge", g.Identifier)
+	require.Equal(t, map[string]string{
+		"git.authheadersecret": "GIT_AUTH_HEADER",
+		"git.authtokensecret":  "GIT_AUTH_TOKEN",
+		"git.debugcommands":    "true",
+		"git.fullurl":          "https://github.com/docker/buildx.git",
+	}, g.Attrs)
+}
+
+func marshalGitContext(t *testing.T, st *llb.State) *pb.SourceOp {
+	t.Helper()
+
+	def, err := st.Marshal(context.TODO())
+	require.NoError(t, err)
+
+	m, arr := parseDef(t, def.Def)
+	require.Equal(t, 2, len(arr))
+
+	dgst, idx := last(t, arr)
+	require.Equal(t, 0, idx)
+	require.Equal(t, m[dgst], arr[0])
+
+	return arr[0].Op.(*pb.Op_Source).Source
+}
+
+func parseDef(t *testing.T, def [][]byte) (map[string]*pb.Op, []*pb.Op) {
+	t.Helper()
+
+	m := map[string]*pb.Op{}
+	arr := make([]*pb.Op, 0, len(def))
+
+	for _, dt := range def {
+		var op pb.Op
+		err := op.Unmarshal(dt)
+		require.NoError(t, err)
+		dgst := digest.FromBytes(dt)
+		m[string(dgst)] = &op
+		arr = append(arr, &op)
+	}
+
+	return m, arr
+}
+
+func last(t *testing.T, arr []*pb.Op) (string, int) {
+	t.Helper()
+
+	require.Greater(t, len(arr), 1)
+
+	op := arr[len(arr)-1]
+	require.Equal(t, 1, len(op.Inputs))
+	return op.Inputs[0].Digest, int(op.Inputs[0].Index)
+}
diff --git a/frontend/dockerui/config.go b/frontend/dockerui/config.go
@@ -51,6 +51,7 @@ const (
 	keyHostnameArg          = "build-arg:BUILDKIT_SANDBOX_HOSTNAME"
 	keyDockerfileLintArg    = "build-arg:BUILDKIT_DOCKERFILE_CHECK"
 	keyContextKeepGitDirArg = "build-arg:BUILDKIT_CONTEXT_KEEP_GIT_DIR"
+	keyDebugGitCommandsArg  = "build-arg:BUILDKIT_DEBUG_GIT_COMMANDS"
 	keySourceDateEpoch      = "build-arg:SOURCE_DATE_EPOCH"
 )
 
diff --git a/frontend/dockerui/context.go b/frontend/dockerui/context.go
@@ -73,7 +73,11 @@ func (bc *Client) initContext(ctx context.Context) (*buildContext, error) {
 	if v, err := strconv.ParseBool(opts[keyContextKeepGitDirArg]); err == nil {
 		keepGit = &v
 	}
-	if st, ok, err := DetectGitContext(opts[localNameContext], keepGit); ok {
+	var debugGitCommands *bool
+	if v, err := strconv.ParseBool(opts[keyDebugGitCommandsArg]); err == nil {
+		debugGitCommands = &v
+	}
+	if st, ok, err := DetectGitContext(opts[localNameContext], keepGit, debugGitCommands); ok {
 		if err != nil {
 			return nil, err
 		}
@@ -143,7 +147,7 @@ func (bc *Client) initContext(ctx context.Context) (*buildContext, error) {
 	return bctx, nil
 }
 
-func DetectGitContext(ref string, keepGit *bool) (*llb.State, bool, error) {
+func DetectGitContext(ref string, keepGit *bool, debugGitCommands *bool) (*llb.State, bool, error) {
 	g, isGit, err := dfgitutil.ParseGitRef(ref)
 	if err != nil {
 		return nil, isGit, err
@@ -158,6 +162,9 @@ func DetectGitContext(ref string, keepGit *bool) (*llb.State, bool, error) {
 	if keepGit != nil && *keepGit {
 		gitOpts = append(gitOpts, llb.KeepGitDir())
 	}
+	if debugGitCommands != nil && *debugGitCommands {
+		gitOpts = append(gitOpts, llb.GitDebugCommands())
+	}
 	if g.SubDir != "" {
 		gitOpts = append(gitOpts, llb.GitSubDir(g.SubDir))
 	}
diff --git a/frontend/dockerui/namedcontext.go b/frontend/dockerui/namedcontext.go
@@ -141,7 +141,7 @@ func (nc *NamedContext) load(ctx context.Context, count int) (*llb.State, *docke
 		}
 		return &st, &img, nil
 	case "git":
-		st, ok, err := DetectGitContext(nc.input, nil)
+		st, ok, err := DetectGitContext(nc.input, nil, nil)
 		if !ok {
 			return nil, nil, errors.Errorf("invalid git context %s", nc.input)
 		}
@@ -150,7 +150,7 @@ func (nc *NamedContext) load(ctx context.Context, count int) (*llb.State, *docke
 		}
 		return st, nil, nil
 	case "http", "https":
-		st, ok, err := DetectGitContext(nc.input, nil)
+		st, ok, err := DetectGitContext(nc.input, nil, nil)
 		if !ok {
 			httpst := llb.HTTP(nc.input, llb.WithCustomName("[context "+nc.nameWithPlatform+"] "+nc.input))
 			st = &httpst
diff --git a/solver/pb/attr.go b/solver/pb/attr.go
@@ -8,6 +8,7 @@ const AttrKnownSSHHosts = "git.knownsshhosts"
 const AttrMountSSHSock = "git.mountsshsock"
 const AttrGitChecksum = "git.checksum"
 const AttrGitSkipSubmodules = "git.skipsubmodules"
+const AttrGitDebugCommands = "git.debugcommands"
 
 const AttrGitSignatureVerifyPubKey = "git.sig.pubkey"
 const AttrGitSignatureVerifyRejectExpired = "git.sig.rejectexpired"
diff --git a/solver/pb/caps.go b/solver/pb/caps.go
@@ -33,6 +33,7 @@ const (
 	CapSourceGitSubdir          apicaps.CapID = "source.git.subdir"
 	CapSourceGitChecksum        apicaps.CapID = "source.git.checksum"
 	CapSourceGitSkipSubmodules  apicaps.CapID = "source.git.skipsubmodules"
+	CapSourceGitDebugCommands   apicaps.CapID = "source.git.debugcommands"
 	CapSourceGitSignatureVerify apicaps.CapID = "source.git.signatureverify"
 
 	CapSourceHTTP         apicaps.CapID = "source.http"
@@ -249,6 +250,12 @@ func init() {
 		Status:  apicaps.CapStatusExperimental,
 	})
 
+	Caps.Init(apicaps.Cap{
+		ID:      CapSourceGitDebugCommands,
+		Enabled: true,
+		Status:  apicaps.CapStatusExperimental,
+	})
+
 	Caps.Init(apicaps.Cap{
 		ID:      CapSourceGitSignatureVerify,
 		Enabled: true,
diff --git a/source/git/identifier.go b/source/git/identifier.go
@@ -21,6 +21,7 @@ type GitIdentifier struct {
 	MountSSHSock     string
 	KnownSSHHosts    string
 	SkipSubmodules   bool
+	DebugCommands    bool
 
 	VerifySignature *GitSignatureVerifyOptions
 }
diff --git a/source/git/source.go b/source/git/source.go
@@ -114,6 +114,10 @@ func (gs *Source) Identifier(scheme, ref string, attrs map[string]string, platfo
 			if v == "true" {
 				id.SkipSubmodules = true
 			}
+		case pb.AttrGitDebugCommands:
+			if v == "true" {
+				id.DebugCommands = true
+			}
 		case pb.AttrGitSignatureVerifyPubKey:
 			if id.VerifySignature == nil {
 				id.VerifySignature = &GitSignatureVerifyOptions{}
@@ -141,7 +145,7 @@ func (gs *Source) Identifier(scheme, ref string, attrs map[string]string, platfo
 }
 
 // needs to be called with repo lock
-func (gs *Source) mountRemote(ctx context.Context, remote string, authArgs []string, sha256 bool, reset bool, g session.Group) (target string, release func() error, retErr error) {
+func (gs *Source) mountRemote(ctx context.Context, remote string, authArgs []string, debugCommands bool, sha256 bool, reset bool, g session.Group) (target string, release func() error, retErr error) {
 	sis, err := searchGitRemote(ctx, gs.cache, remote)
 	if err != nil {
 		return "", nil, errors.Wrapf(err, "failed to search metadata for %s", urlutil.RedactCredentials(remote))
@@ -206,6 +210,7 @@ func (gs *Source) mountRemote(ctx context.Context, remote string, authArgs []str
 	git := gitCLI(
 		gitutil.WithGitDir(dir),
 		gitutil.WithArgs(authArgs...),
+		gitutil.WithDebugCommands(debugCommands),
 	)
 
 	if initializeRepo {
@@ -844,7 +849,7 @@ func (gs *gitSourceHandler) tryRemoteFetch(ctx context.Context, g session.Group,
 	}
 	repo.releasers = append(repo.releasers, cleanup)
 
-	gitDir, unmountGitDir, err := gs.mountRemote(ctx, gs.src.Remote, gs.authArgs, gs.sha256, reset, g)
+	gitDir, unmountGitDir, err := gs.mountRemote(ctx, gs.src.Remote, gs.authArgs, gs.src.DebugCommands, gs.sha256, reset, g)
 	if err != nil {
 		return nil, err
 	}
@@ -1207,6 +1212,7 @@ func (gs *gitSourceHandler) emptyGitCli(ctx context.Context, g session.Group, op
 
 	opts = append([]gitutil.Option{
 		gitutil.WithArgs(gs.authArgs...),
+		gitutil.WithDebugCommands(gs.src.DebugCommands),
 		gitutil.WithSSHAuthSock(sock),
 		gitutil.WithSSHKnownHosts(knownHosts),
 	}, opts...)
diff --git a/source/git/source_test.go b/source/git/source_test.go
@@ -14,6 +14,7 @@ import (
 	"runtime"
 	"strconv"
 	"strings"
+	"sync"
 	"testing"
 	"time"
 
@@ -57,6 +58,14 @@ func TestRepeatedFetchKeepGitDirSHA256(t *testing.T) {
 	testRepeatedFetch(t, true, "sha256")
 }
 
+func TestDebugCommandsSHA1(t *testing.T) {
+	testDebugCommands(t, "sha1")
+}
+
+func TestDebugCommandsSHA256(t *testing.T) {
+	testDebugCommands(t, "sha256")
+}
+
 func testRepeatedFetch(t *testing.T, keepGitDir bool, format string) {
 	if runtime.GOOS == "windows" {
 		t.Skip("Depends on unimplemented containerd bind-mount support on Windows")
@@ -175,6 +184,48 @@ func testRepeatedFetch(t *testing.T, keepGitDir bool, format string) {
 	require.Equal(t, pin3, pin4)
 }
 
+func testDebugCommands(t *testing.T, format string) {
+	if runtime.GOOS == "windows" {
+		t.Skip("Depends on unimplemented containerd bind-mount support on Windows")
+	}
+
+	t.Parallel()
+	ctx, logs := captureProgressLogs(context.Background(), t)
+
+	gs := setupGitSource(t, t.TempDir())
+	repo := setupGitRepo(t, format)
+
+	id := &GitIdentifier{Remote: repo.mainURL, Ref: "feature", KeepGitDir: true, DebugCommands: true}
+	g, err := gs.Resolve(ctx, id, nil, nil)
+	require.NoError(t, err)
+
+	ref, err := g.Snapshot(ctx, nil)
+	require.NoError(t, err)
+	defer ref.Release(context.TODO())
+
+	_ = mountRef(ctx, t, ref)
+
+	require.Eventually(t, func() bool {
+		out := logs.String()
+		return strings.Contains(out, "+ git ") && strings.Contains(out, " fetch ") && strings.Contains(out, " checkout ")
+	}, 5*time.Second, 50*time.Millisecond)
+}
+
+func mountRef(ctx context.Context, t *testing.T, ref cache.ImmutableRef) string {
+	t.Helper()
+
+	mount, err := ref.Mount(ctx, true, nil)
+	require.NoError(t, err)
+
+	lm := snapshot.LocalMounter(mount)
+	dir, err := lm.Mount()
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		require.NoError(t, lm.Unmount())
+	})
+	return dir
+}
+
 func TestFetchBySHA1(t *testing.T) {
 	testFetchBySHA(t, "sha1", false)
 }
@@ -2365,3 +2416,45 @@ func logProgressStreams(ctx context.Context, t *testing.T) context.Context {
 	}()
 	return ctx
 }
+
+type progressLogBuffer struct {
+	mu sync.Mutex
+	sb strings.Builder
+}
+
+func (b *progressLogBuffer) Write(dt []byte) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.sb.Write(dt)
+}
+
+func (b *progressLogBuffer) String() string {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	return b.sb.String()
+}
+
+func captureProgressLogs(ctx context.Context, t *testing.T) (context.Context, *progressLogBuffer) {
+	pr, ctx, cancel := progress.NewContext(ctx)
+	buf := &progressLogBuffer{}
+	done := make(chan struct{})
+	t.Cleanup(func() {
+		cancel(errors.WithStack(context.Canceled))
+		<-done
+	})
+	go func() {
+		defer close(done)
+		for {
+			prog, err := pr.Read(context.Background())
+			if err != nil {
+				return
+			}
+			for _, log := range prog {
+				if lsys, ok := log.Sys.(client.VertexLog); ok {
+					buf.Write(lsys.Data)
+				}
+			}
+		}
+	}()
+	return ctx, buf
+}
diff --git a/util/gitutil/git_cli.go b/util/gitutil/git_cli.go
diff --git a/util/gitutil/git_cli_test.go b/util/gitutil/git_cli_test.go

Original file line number	Diff line number	Diff line change
`@@ -51,6 +51,7 @@ const (`
`51`	`51`	`keyHostnameArg = "build-arg:BUILDKIT_SANDBOX_HOSTNAME"`
`52`	`52`	`keyDockerfileLintArg = "build-arg:BUILDKIT_DOCKERFILE_CHECK"`
`53`	`53`	`keyContextKeepGitDirArg = "build-arg:BUILDKIT_CONTEXT_KEEP_GIT_DIR"`
	`54`	`+ keyDebugGitCommandsArg = "build-arg:BUILDKIT_DEBUG_GIT_COMMANDS"`
`54`	`55`	`keySourceDateEpoch = "build-arg:SOURCE_DATE_EPOCH"`
`55`	`56`	`)`
`56`	`57`
Original file line number	Diff line number	Diff line change
`@@ -73,7 +73,11 @@ func (bc Client) initContext(ctx context.Context) (buildContext, error) {`
`73`	`73`	`if v, err := strconv.ParseBool(opts[keyContextKeepGitDirArg]); err == nil {`
`74`	`74`	`keepGit = &v`
`75`	`75`	`}`
`76`		`- if st, ok, err := DetectGitContext(opts[localNameContext], keepGit); ok {`
	`76`	`+ var debugGitCommands *bool`
	`77`	`+ if v, err := strconv.ParseBool(opts[keyDebugGitCommandsArg]); err == nil {`
	`78`	`+ debugGitCommands = &v`
	`79`	`+ }`
	`80`	`+ if st, ok, err := DetectGitContext(opts[localNameContext], keepGit, debugGitCommands); ok {`
`77`	`81`	`if err != nil {`
`78`	`82`	`return nil, err`
`79`	`83`	`}`
`@@ -143,7 +147,7 @@ func (bc Client) initContext(ctx context.Context) (buildContext, error) {`
`143`	`147`	`return bctx, nil`
`144`	`148`	`}`
`145`	`149`
`146`		`-func DetectGitContext(ref string, keepGit bool) (llb.State, bool, error) {`
	`150`	`+func DetectGitContext(ref string, keepGit bool, debugGitCommands bool) (*llb.State, bool, error) {`
`147`	`151`	`g, isGit, err := dfgitutil.ParseGitRef(ref)`
`148`	`152`	`if err != nil {`
`149`	`153`	`return nil, isGit, err`
`@@ -158,6 +162,9 @@ func DetectGitContext(ref string, keepGit bool) (llb.State, bool, error) {`
`158`	`162`	`if keepGit != nil && *keepGit {`
`159`	`163`	`gitOpts = append(gitOpts, llb.KeepGitDir())`
`160`	`164`	`}`
	`165`	`+ if debugGitCommands != nil && *debugGitCommands {`
	`166`	`+ gitOpts = append(gitOpts, llb.GitDebugCommands())`
	`167`	`+ }`
`161`	`168`	`if g.SubDir != "" {`
`162`	`169`	`gitOpts = append(gitOpts, llb.GitSubDir(g.SubDir))`
`163`	`170`	`}`
Original file line number	Diff line number	Diff line change
`@@ -141,7 +141,7 @@ func (nc NamedContext) load(ctx context.Context, count int) (llb.State, *docke`
`141`	`141`	`}`
`142`	`142`	`return &st, &img, nil`
`143`	`143`	`case "git":`
`144`		`- st, ok, err := DetectGitContext(nc.input, nil)`
	`144`	`+ st, ok, err := DetectGitContext(nc.input, nil, nil)`
`145`	`145`	`if !ok {`
`146`	`146`	`return nil, nil, errors.Errorf("invalid git context %s", nc.input)`
`147`	`147`	`}`
`@@ -150,7 +150,7 @@ func (nc NamedContext) load(ctx context.Context, count int) (llb.State, *docke`
`150`	`150`	`}`
`151`	`151`	`return st, nil, nil`
`152`	`152`	`case "http", "https":`
`153`		`- st, ok, err := DetectGitContext(nc.input, nil)`
	`153`	`+ st, ok, err := DetectGitContext(nc.input, nil, nil)`
`154`	`154`	`if !ok {`
`155`	`155`	`httpst := llb.HTTP(nc.input, llb.WithCustomName("[context "+nc.nameWithPlatform+"] "+nc.input))`
`156`	`156`	`st = &httpst`
Original file line number	Diff line number	Diff line change
`@@ -21,6 +21,7 @@ type GitIdentifier struct {`
`21`	`21`	`MountSSHSock string`
`22`	`22`	`KnownSSHHosts string`
`23`	`23`	`SkipSubmodules bool`
	`24`	`+ DebugCommands bool`
`24`	`25`
`25`	`26`	`VerifySignature *GitSignatureVerifyOptions`
`26`	`27`	`}`