Clarify the git command Stdin hanging problem (#26967)

1 files changed, 12 insertions, 2 deletions

diff --git a/modules/git/command.go b/modules/git/command.go
index c38fd04696..f095bb18be 100644
--- a/modules/git/command.go
+++ b/modules/git/command.go
@@ -221,8 +221,18 @@ type RunOpts struct {
 	Dir string
 
 	Stdout, Stderr io.Writer
-	Stdin          io.Reader
-	PipelineFunc   func(context.Context, context.CancelFunc) error
+
+	// 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 {