Move git command to git/gitcmd (#35483)

The name cmd is already used in many places and may cause conflicts, so
I chose `gitcmd` instead to minimize potential naming conflicts.

modules/git/gitcmd/command.go

@@ -0,0 +1,447 @@
+// Copyright 2015 The Gogs Authors. All rights reserved.
+// Copyright 2016 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package gitcmd
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"time"
+
+	"code.gitea.io/gitea/modules/git/internal" //nolint:depguard // only this file can use the internal type CmdArg, other files and packages should use AddXxx functions
+	"code.gitea.io/gitea/modules/gtprof"
+	"code.gitea.io/gitea/modules/log"
+	"code.gitea.io/gitea/modules/process"
+	"code.gitea.io/gitea/modules/util"
+)
+
+// TrustedCmdArgs returns the trusted arguments for git command.
+// It's mainly for passing user-provided and trusted arguments to git command
+// In most cases, it shouldn't be used. Use AddXxx function instead
+type TrustedCmdArgs []internal.CmdArg
+
+// defaultCommandExecutionTimeout default command execution timeout duration
+var defaultCommandExecutionTimeout = 360 * time.Second
+
+func SetDefaultCommandExecutionTimeout(timeout time.Duration) {
+	defaultCommandExecutionTimeout = timeout
+}
+
+// DefaultLocale is the default LC_ALL to run git commands in.
+const DefaultLocale = "C"
+
+// Command represents a command with its subcommands or arguments.
+type Command struct {
+	prog       string
+	args       []string
+	brokenArgs []string
+	cmd        *exec.Cmd // for debug purpose only
+	configArgs []string
+}
+
+func logArgSanitize(arg string) string {
+	if strings.Contains(arg, "://") && strings.Contains(arg, "@") {
+		return util.SanitizeCredentialURLs(arg)
+	} else if filepath.IsAbs(arg) {
+		base := filepath.Base(arg)
+		dir := filepath.Dir(arg)
+		return ".../" + filepath.Join(filepath.Base(dir), base)
+	}
+	return arg
+}
+
+func (c *Command) LogString() string {
+	// WARNING: this function is for debugging purposes only. It's much better than old code (which only joins args with space),
+	// It's impossible to make a simple and 100% correct implementation of argument quoting for different platforms here.
+	debugQuote := func(s string) string {
+		if strings.ContainsAny(s, " `'\"\t\r\n") {
+			return fmt.Sprintf("%q", s)
+		}
+		return s
+	}
+	a := make([]string, 0, len(c.args)+1)
+	a = append(a, debugQuote(c.prog))
+	for i := 0; i < len(c.args); i++ {
+		a = append(a, debugQuote(logArgSanitize(c.args[i])))
+	}
+	return strings.Join(a, " ")
+}
+
+func (c *Command) ProcessState() string {
+	if c.cmd == nil {
+		return ""
+	}
+	return c.cmd.ProcessState.String()
+}
+
+// NewCommand creates and returns a new Git Command based on given command and arguments.
+// Each argument should be safe to be trusted. User-provided arguments should be passed to AddDynamicArguments instead.
+func NewCommand(args ...internal.CmdArg) *Command {
+	cargs := make([]string, 0, len(args))
+	for _, arg := range args {
+		cargs = append(cargs, string(arg))
+	}
+	return &Command{
+		prog: GitExecutable,
+		args: cargs,
+	}
+}
+
+// isSafeArgumentValue checks if the argument is safe to be used as a value (not an option)
+func isSafeArgumentValue(s string) bool {
+	return s == "" || s[0] != '-'
+}
+
+// isValidArgumentOption checks if the argument is a valid option (starting with '-').
+// It doesn't check whether the option is supported or not
+func isValidArgumentOption(s string) bool {
+	return s != "" && s[0] == '-'
+}
+
+// AddArguments adds new git arguments (option/value) to the command. It only accepts string literals, or trusted CmdArg.
+// Type CmdArg is in the internal package, so it can not be used outside of this package directly,
+// it makes sure that user-provided arguments won't cause RCE risks.
+// User-provided arguments should be passed by other AddXxx functions
+func (c *Command) AddArguments(args ...internal.CmdArg) *Command {
+	for _, arg := range args {
+		c.args = append(c.args, string(arg))
+	}
+	return c
+}
+
+// AddOptionValues adds a new option with a list of non-option values
+// For example: AddOptionValues("--opt", val) means 2 arguments: {"--opt", val}.
+// The values are treated as dynamic argument values. It equals to: AddArguments("--opt") then AddDynamicArguments(val).
+func (c *Command) AddOptionValues(opt internal.CmdArg, args ...string) *Command {
+	if !isValidArgumentOption(string(opt)) {
+		c.brokenArgs = append(c.brokenArgs, string(opt))
+		return c
+	}
+	c.args = append(c.args, string(opt))
+	c.AddDynamicArguments(args...)
+	return c
+}
+
+// AddOptionFormat adds a new option with a format string and arguments
+// For example: AddOptionFormat("--opt=%s %s", val1, val2) means 1 argument: {"--opt=val1 val2"}.
+func (c *Command) AddOptionFormat(opt string, args ...any) *Command {
+	if !isValidArgumentOption(opt) {
+		c.brokenArgs = append(c.brokenArgs, opt)
+		return c
+	}
+	// a quick check to make sure the format string matches the number of arguments, to find low-level mistakes ASAP
+	if strings.Count(strings.ReplaceAll(opt, "%%", ""), "%") != len(args) {
+		c.brokenArgs = append(c.brokenArgs, opt)
+		return c
+	}
+	s := fmt.Sprintf(opt, args...)
+	c.args = append(c.args, s)
+	return c
+}
+
+// AddDynamicArguments adds new dynamic argument values to the command.
+// The arguments may come from user input and can not be trusted, so no leading '-' is allowed to avoid passing options.
+// TODO: in the future, this function can be renamed to AddArgumentValues
+func (c *Command) AddDynamicArguments(args ...string) *Command {
+	for _, arg := range args {
+		if !isSafeArgumentValue(arg) {
+			c.brokenArgs = append(c.brokenArgs, arg)
+		}
+	}
+	if len(c.brokenArgs) != 0 {
+		return c
+	}
+	c.args = append(c.args, args...)
+	return c
+}
+
+// AddDashesAndList adds the "--" and then add the list as arguments, it's usually for adding file list
+// At the moment, this function can be only called once, maybe in future it can be refactored to support multiple calls (if necessary)
+func (c *Command) AddDashesAndList(list ...string) *Command {
+	c.args = append(c.args, "--")
+	// Some old code also checks `arg != ""`, IMO it's not necessary.
+	// If the check is needed, the list should be prepared before the call to this function
+	c.args = append(c.args, list...)
+	return c
+}
+
+func (c *Command) AddConfig(key, value string) *Command {
+	kv := key + "=" + value
+	if !isSafeArgumentValue(kv) {
+		c.brokenArgs = append(c.brokenArgs, key)
+	} else {
+		c.configArgs = append(c.configArgs, "-c", kv)
+	}
+	return c
+}
+
+// ToTrustedCmdArgs converts a list of strings (trusted as argument) to TrustedCmdArgs
+// In most cases, it shouldn't be used. Use NewCommand().AddXxx() function instead
+func ToTrustedCmdArgs(args []string) TrustedCmdArgs {
+	ret := make(TrustedCmdArgs, len(args))
+	for i, arg := range args {
+		ret[i] = internal.CmdArg(arg)
+	}
+	return ret
+}
+
+// RunOpts represents parameters to run the command. If UseContextTimeout is specified, then Timeout is ignored.
+type RunOpts struct {
+	Env               []string
+	Timeout           time.Duration
+	UseContextTimeout bool
+
+	// Dir is the working dir for the git command, however:
+	// FIXME: this could be incorrect in many cases, for example:
+	// * /some/path/.git
+	// * /some/path/.git/gitea-data/data/repositories/user/repo.git
+	// If "user/repo.git" is invalid/broken, then running git command in it will use "/some/path/.git", and produce unexpected results
+	// The correct approach is to use `--git-dir" global argument
+	Dir string
+
+	Stdout, Stderr io.Writer
+
+	// Stdin is used for passing input to the command
+	// The caller must make sure the Stdin writer is closed properly to finish the Run function.
+	// Otherwise, the Run function may hang for long time or forever, especially when the Git's context deadline is not the same as the caller's.
+	// Some common mistakes:
+	// * `defer stdinWriter.Close()` then call `cmd.Run()`: the Run() would never return if the command is killed by timeout
+	// * `go { case <- parentContext.Done(): stdinWriter.Close() }` with `cmd.Run(DefaultTimeout)`: the command would have been killed by timeout but the Run doesn't return until stdinWriter.Close()
+	// * `go { if stdoutReader.Read() err != nil: stdinWriter.Close() }` with `cmd.Run()`: the stdoutReader may never return error if the command is killed by timeout
+	// In the future, ideally the git module itself should have full control of the stdin, to avoid such problems and make it easier to refactor to a better architecture.
+	Stdin io.Reader
+
+	PipelineFunc func(context.Context, context.CancelFunc) error
+}
+
+func commonBaseEnvs() []string {
+	envs := []string{
+		// Make Gitea use internal git config only, to prevent conflicts with user's git config
+		// It's better to use GIT_CONFIG_GLOBAL, but it requires git >= 2.32, so we still use HOME at the moment.
+		"HOME=" + HomeDir(),
+		// Avoid using system git config, it would cause problems (eg: use macOS osxkeychain to show a modal dialog, auto installing lfs hooks)
+		// This might be a breaking change in 1.24, because some users said that they have put some configs like "receive.certNonceSeed" in "/etc/gitconfig"
+		// For these users, they need to migrate the necessary configs to Gitea's git config file manually.
+		"GIT_CONFIG_NOSYSTEM=1",
+		// Ignore replace references (https://git-scm.com/docs/git-replace)
+		"GIT_NO_REPLACE_OBJECTS=1",
+	}
+
+	// some environment variables should be passed to git command
+	passThroughEnvKeys := []string{
+		"GNUPGHOME", // git may call gnupg to do commit signing
+	}
+	for _, key := range passThroughEnvKeys {
+		if val, ok := os.LookupEnv(key); ok {
+			envs = append(envs, key+"="+val)
+		}
+	}
+	return envs
+}
+
+// CommonGitCmdEnvs returns the common environment variables for a "git" command.
+func CommonGitCmdEnvs() []string {
+	return append(commonBaseEnvs(), []string{
+		"LC_ALL=" + DefaultLocale,
+		"GIT_TERMINAL_PROMPT=0", // avoid prompting for credentials interactively, supported since git v2.3
+	}...)
+}
+
+// CommonCmdServEnvs is like CommonGitCmdEnvs, but it only returns minimal required environment variables for the "gitea serv" command
+func CommonCmdServEnvs() []string {
+	return commonBaseEnvs()
+}
+
+var ErrBrokenCommand = errors.New("git command is broken")
+
+// Run runs the command with the RunOpts
+func (c *Command) Run(ctx context.Context, opts *RunOpts) error {
+	return c.run(ctx, 1, opts)
+}
+
+func (c *Command) run(ctx context.Context, skip int, opts *RunOpts) error {
+	if len(c.brokenArgs) != 0 {
+		log.Error("git command is broken: %s, broken args: %s", c.LogString(), strings.Join(c.brokenArgs, " "))
+		return ErrBrokenCommand
+	}
+	if opts == nil {
+		opts = &RunOpts{}
+	}
+
+	// We must not change the provided options
+	timeout := opts.Timeout
+	if timeout <= 0 {
+		timeout = defaultCommandExecutionTimeout
+	}
+
+	cmdLogString := c.LogString()
+	callerInfo := util.CallerFuncName(1 /* util */ + 1 /* this */ + skip /* parent */)
+	if pos := strings.LastIndex(callerInfo, "/"); pos >= 0 {
+		callerInfo = callerInfo[pos+1:]
+	}
+	// these logs are for debugging purposes only, so no guarantee of correctness or stability
+	desc := fmt.Sprintf("git.Run(by:%s, repo:%s): %s", callerInfo, logArgSanitize(opts.Dir), cmdLogString)
+	log.Debug("git.Command: %s", desc)
+
+	_, span := gtprof.GetTracer().Start(ctx, gtprof.TraceSpanGitRun)
+	defer span.End()
+	span.SetAttributeString(gtprof.TraceAttrFuncCaller, callerInfo)
+	span.SetAttributeString(gtprof.TraceAttrGitCommand, cmdLogString)
+
+	var cancel context.CancelFunc
+	var finished context.CancelFunc
+
+	if opts.UseContextTimeout {
+		ctx, cancel, finished = process.GetManager().AddContext(ctx, desc)
+	} else {
+		ctx, cancel, finished = process.GetManager().AddContextTimeout(ctx, timeout, desc)
+	}
+	defer finished()
+
+	startTime := time.Now()
+
+	cmd := exec.CommandContext(ctx, c.prog, append(c.configArgs, c.args...)...)
+	c.cmd = cmd // for debug purpose only
+	if opts.Env == nil {
+		cmd.Env = os.Environ()
+	} else {
+		cmd.Env = opts.Env
+	}
+
+	process.SetSysProcAttribute(cmd)
+	cmd.Env = append(cmd.Env, CommonGitCmdEnvs()...)
+	cmd.Dir = opts.Dir
+	cmd.Stdout = opts.Stdout
+	cmd.Stderr = opts.Stderr
+	cmd.Stdin = opts.Stdin
+	if err := cmd.Start(); err != nil {
+		return err
+	}
+
+	if opts.PipelineFunc != nil {
+		err := opts.PipelineFunc(ctx, cancel)
+		if err != nil {
+			cancel()
+			_ = cmd.Wait()
+			return err
+		}
+	}
+
+	err := cmd.Wait()
+	elapsed := time.Since(startTime)
+	if elapsed > time.Second {
+		log.Debug("slow git.Command.Run: %s (%s)", c, elapsed)
+	}
+
+	// We need to check if the context is canceled by the program on Windows.
+	// This is because Windows does not have signal checking when terminating the process.
+	// It always returns exit code 1, unlike Linux, which has many exit codes for signals.
+	// `err.Error()` returns "exit status 1" when using the `git check-attr` command after the context is canceled.
+	if runtime.GOOS == "windows" &&
+		err != nil &&
+		(err.Error() == "" || err.Error() == "exit status 1") &&
+		cmd.ProcessState.ExitCode() == 1 &&
+		ctx.Err() == context.Canceled {
+		return ctx.Err()
+	}
+
+	if err != nil && ctx.Err() != context.DeadlineExceeded {
+		return err
+	}
+
+	return ctx.Err()
+}
+
+type RunStdError interface {
+	error
+	Unwrap() error
+	Stderr() string
+}
+
+type runStdError struct {
+	err    error
+	stderr string
+	errMsg string
+}
+
+func (r *runStdError) Error() string {
+	// the stderr must be in the returned error text, some code only checks `strings.Contains(err.Error(), "git error")`
+	if r.errMsg == "" {
+		r.errMsg = ConcatenateError(r.err, r.stderr).Error()
+	}
+	return r.errMsg
+}
+
+func (r *runStdError) Unwrap() error {
+	return r.err
+}
+
+func (r *runStdError) Stderr() string {
+	return r.stderr
+}
+
+func IsErrorExitCode(err error, code int) bool {
+	var exitError *exec.ExitError
+	if errors.As(err, &exitError) {
+		return exitError.ExitCode() == code
+	}
+	return false
+}
+
+// RunStdString runs the command with options and returns stdout/stderr as string. and store stderr to returned error (err combined with stderr).
+func (c *Command) RunStdString(ctx context.Context, opts *RunOpts) (stdout, stderr string, runErr RunStdError) {
+	stdoutBytes, stderrBytes, err := c.runStdBytes(ctx, opts)
+	stdout = util.UnsafeBytesToString(stdoutBytes)
+	stderr = util.UnsafeBytesToString(stderrBytes)
+	if err != nil {
+		return stdout, stderr, &runStdError{err: err, stderr: stderr}
+	}
+	// even if there is no err, there could still be some stderr output, so we just return stdout/stderr as they are
+	return stdout, stderr, nil
+}
+
+// RunStdBytes runs the command with options and returns stdout/stderr as bytes. and store stderr to returned error (err combined with stderr).
+func (c *Command) RunStdBytes(ctx context.Context, opts *RunOpts) (stdout, stderr []byte, runErr RunStdError) {
+	return c.runStdBytes(ctx, opts)
+}
+
+func (c *Command) runStdBytes(ctx context.Context, opts *RunOpts) (stdout, stderr []byte, runErr RunStdError) {
+	if opts == nil {
+		opts = &RunOpts{}
+	}
+	if opts.Stdout != nil || opts.Stderr != nil {
+		// we must panic here, otherwise there would be bugs if developers set Stdin/Stderr by mistake, and it would be very difficult to debug
+		panic("stdout and stderr field must be nil when using RunStdBytes")
+	}
+	stdoutBuf := &bytes.Buffer{}
+	stderrBuf := &bytes.Buffer{}
+
+	// We must not change the provided options as it could break future calls - therefore make a copy.
+	newOpts := &RunOpts{
+		Env:               opts.Env,
+		Timeout:           opts.Timeout,
+		UseContextTimeout: opts.UseContextTimeout,
+		Dir:               opts.Dir,
+		Stdout:            stdoutBuf,
+		Stderr:            stderrBuf,
+		Stdin:             opts.Stdin,
+		PipelineFunc:      opts.PipelineFunc,
+	}
+
+	err := c.run(ctx, 2, newOpts)
+	stderr = stderrBuf.Bytes()
+	if err != nil {
+		return nil, stderr, &runStdError{err: err, stderr: util.UnsafeBytesToString(stderr)}
+	}
+	// even if there is no err, there could still be some stderr output
+	return stdoutBuf.Bytes(), stderr, nil
+}

modules/git/gitcmd/command_race_test.go

@@ -0,0 +1,38 @@
+// Copyright 2017 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+//go:build race
+
+package gitcmd
+
+import (
+	"context"
+	"testing"
+	"time"
+)
+
+func TestRunWithContextNoTimeout(t *testing.T) {
+	maxLoops := 10
+
+	// 'git --version' does not block so it must be finished before the timeout triggered.
+	cmd := NewCommand("--version")
+	for i := 0; i < maxLoops; i++ {
+		if err := cmd.Run(t.Context(), &RunOpts{}); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestRunWithContextTimeout(t *testing.T) {
+	maxLoops := 10
+
+	// 'git hash-object --stdin' blocks on stdin so we can have the timeout triggered.
+	cmd := NewCommand("hash-object", "--stdin")
+	for i := 0; i < maxLoops; i++ {
+		if err := cmd.Run(t.Context(), &RunOpts{Timeout: 1 * time.Millisecond}); err != nil {
+			if err != context.DeadlineExceeded {
+				t.Fatalf("Testing %d/%d: %v", i, maxLoops, err)
+			}
+		}
+	}
+}

modules/git/gitcmd/command_test.go

@@ -0,0 +1,77 @@
+// Copyright 2022 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package gitcmd
+
+import (
+	"fmt"
+	"os"
+	"testing"
+
+	"code.gitea.io/gitea/modules/setting"
+	"code.gitea.io/gitea/modules/tempdir"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestMain(m *testing.M) {
+	gitHomePath, cleanup, err := tempdir.OsTempDir("gitea-test").MkdirTempRandom("git-home")
+	if err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "unable to create temp dir: %v", err)
+		os.Exit(1)
+	}
+	defer cleanup()
+
+	setting.Git.HomePath = gitHomePath
+}
+
+func TestRunWithContextStd(t *testing.T) {
+	cmd := NewCommand("--version")
+	stdout, stderr, err := cmd.RunStdString(t.Context(), &RunOpts{})
+	assert.NoError(t, err)
+	assert.Empty(t, stderr)
+	assert.Contains(t, stdout, "git version")
+
+	cmd = NewCommand("--no-such-arg")
+	stdout, stderr, err = cmd.RunStdString(t.Context(), &RunOpts{})
+	if assert.Error(t, err) {
+		assert.Equal(t, stderr, err.Stderr())
+		assert.Contains(t, err.Stderr(), "unknown option:")
+		assert.Contains(t, err.Error(), "exit status 129 - unknown option:")
+		assert.Empty(t, stdout)
+	}
+
+	cmd = NewCommand()
+	cmd.AddDynamicArguments("-test")
+	assert.ErrorIs(t, cmd.Run(t.Context(), &RunOpts{}), ErrBrokenCommand)
+
+	cmd = NewCommand()
+	cmd.AddDynamicArguments("--test")
+	assert.ErrorIs(t, cmd.Run(t.Context(), &RunOpts{}), ErrBrokenCommand)
+
+	subCmd := "version"
+	cmd = NewCommand().AddDynamicArguments(subCmd) // for test purpose only, the sub-command should never be dynamic for production
+	stdout, stderr, err = cmd.RunStdString(t.Context(), &RunOpts{})
+	assert.NoError(t, err)
+	assert.Empty(t, stderr)
+	assert.Contains(t, stdout, "git version")
+}
+
+func TestGitArgument(t *testing.T) {
+	assert.True(t, isValidArgumentOption("-x"))
+	assert.True(t, isValidArgumentOption("--xx"))
+	assert.False(t, isValidArgumentOption(""))
+	assert.False(t, isValidArgumentOption("x"))
+
+	assert.True(t, isSafeArgumentValue(""))
+	assert.True(t, isSafeArgumentValue("x"))
+	assert.False(t, isSafeArgumentValue("-x"))
+}
+
+func TestCommandString(t *testing.T) {
+	cmd := NewCommand("a", "-m msg", "it's a test", `say "hello"`)
+	assert.Equal(t, cmd.prog+` a "-m msg" "it's a test" "say \"hello\""`, cmd.LogString())
+
+	cmd = NewCommand("url: https://a:b@c/", "/root/dir-a/dir-b")
+	assert.Equal(t, cmd.prog+` "url: https://sanitized-credential@c/" .../dir-a/dir-b`, cmd.LogString())
+}

modules/git/gitcmd/env.go

@@ -0,0 +1,40 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package gitcmd
+
+import (
+	"fmt"
+	"os/exec"
+
+	"code.gitea.io/gitea/modules/log"
+	"code.gitea.io/gitea/modules/setting"
+)
+
+var GitExecutable = "git" // the command name of git, will be updated to an absolute path during initialization
+
+// SetExecutablePath changes the path of git executable and checks the file permission and version.
+func SetExecutablePath(path string) error {
+	// If path is empty, we use the default value of GitExecutable "git" to search for the location of git.
+	if path != "" {
+		GitExecutable = path
+	}
+	absPath, err := exec.LookPath(GitExecutable)
+	if err != nil {
+		return fmt.Errorf("git not found: %w", err)
+	}
+	GitExecutable = absPath
+	return nil
+}
+
+// HomeDir is the home dir for git to store the global config file used by Gitea internally
+func HomeDir() string {
+	if setting.Git.HomePath == "" {
+		// strict check, make sure the git module is initialized correctly.
+		// attention: when the git module is called in gitea sub-command (serv/hook), the log module might not obviously show messages to users/developers.
+		// for example: if there is gitea git hook code calling NewCommand before git.InitXxx, the integration test won't show the real failure reasons.
+		log.Fatal("Unable to init Git's HomeDir, incorrect initialization of the setting and git modules")
+		return ""
+	}
+	return setting.Git.HomePath
+}

modules/git/gitcmd/utils.go

@@ -0,0 +1,14 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package gitcmd
+
+import "fmt"
+
+// ConcatenateError concatenats an error with stderr string
+func ConcatenateError(err error, stderr string) error {
+	if len(stderr) == 0 {
+		return err
+	}
+	return fmt.Errorf("%w - %s", err, stderr)
+}