gitcmd

package
v0.0.0-...-bb05487 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 31, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrBrokenCommand = errors.New("git command is broken")
View Source 
var GitExecutable = "git" // the command name of git, will be updated to an absolute path during initialization

Functions

func CommonCmdServEnvs 

func CommonCmdServEnvs() []string

CommonCmdServEnvs is like CommonGitCmdEnvs, but it only returns minimal required environment variables for the "gitea serv" command

func CommonGitCmdEnvs 

func CommonGitCmdEnvs() []string

CommonGitCmdEnvs returns the common environment variables for a "git" command.

func ErrorAsStderr 

func ErrorAsStderr(err error) (string, bool)

func HomeDir 

func HomeDir() string

HomeDir is the home dir for git to store the global config file used by Gitea internally

func IsErrorCanceledOrKilled 

func IsErrorCanceledOrKilled(err error) bool

func IsErrorExitCode 

func IsErrorExitCode(err error, code int) bool

func IsErrorSignalKilled 

func IsErrorSignalKilled(err error) bool

func IsStdErrorNotValidObjectName 

func IsStdErrorNotValidObjectName(err error) bool

func SetExecutablePath 

func SetExecutablePath(path string) error

SetExecutablePath changes the path of git executable and checks the file permission and version.

func StderrHasPrefix 

func StderrHasPrefix(err error, prefix string) bool

func UnwrapPipelineError 

func UnwrapPipelineError(err error) (error, bool)

Types

type Command 

type Command struct {
	// contains filtered or unexported fields
}

Command represents a command with its subcommands or arguments.

func NewCommand 

func NewCommand(args ...internal.CmdArg) *Command

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 (*Command) AddArguments 

func (c *Command) AddArguments(args ...internal.CmdArg) *Command

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 (*Command) AddConfig 

func (c *Command) AddConfig(key, value string) *Command

func (*Command) AddDashesAndList 

func (c *Command) AddDashesAndList(list ...string) *Command

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 (*Command) AddDynamicArguments 

func (c *Command) AddDynamicArguments(args ...string) *Command

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 (*Command) AddOptionFormat 

func (c *Command) AddOptionFormat(opt string, args ...any) *Command

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 (*Command) AddOptionValues 

func (c *Command) AddOptionValues(opt internal.CmdArg, args ...string) *Command

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 (*Command) DebugKill 

func (c *Command) DebugKill()

func (*Command) LogString 

func (c *Command) LogString() string

func (*Command) MakeStderrPipe 

func (c *Command) MakeStderrPipe() (reader PipeReader, closer func())

MakeStderrPipe is like MakeStdoutPipe, but for stderr.

func (*Command) MakeStdinPipe 

func (c *Command) MakeStdinPipe() (writer PipeWriter, closer func())

MakeStdinPipe creates a writer for the command's stdin. The returned closer function must be called by the caller to close the pipe.

func (*Command) MakeStdinStdoutPipe 

func (c *Command) MakeStdinStdoutPipe() (stdin PipeWriter, stdout PipeReader, closer func())

func (*Command) MakeStdoutPipe 

func (c *Command) MakeStdoutPipe() (reader PipeReader, closer func())

MakeStdoutPipe creates a reader for the command's stdout. The returned closer function must be called by the caller to close the pipe. After the pipe reader is closed, the unread data will be discarded.

If the process (git command) still tries to write after the pipe is closed, the Wait error will be "signal: broken pipe". WithPipelineFunc + Run won't return "broken pipe" error in this case if the callback returns no error. But if you are calling Start / Wait family functions, you should either drain the pipe before close it, or handle the Wait error correctly.

func (*Command) ProcessState 

func (c *Command) ProcessState() string

func (*Command) Run 

func (c *Command) Run(ctx context.Context) (err error)

func (*Command) RunStdBytes 

func (c *Command) RunStdBytes(ctx context.Context) (stdout, stderr []byte, runErr RunStdError)

RunStdBytes runs the command and returns stdout/stderr as bytes. and store stderr to returned error (err combined with stderr).

func (*Command) RunStdString 

func (c *Command) RunStdString(ctx context.Context) (stdout, stderr string, runErr RunStdError)

RunStdString runs the command and returns stdout/stderr as string. and store stderr to returned error (err combined with stderr).

func (*Command) RunWithStderr 

func (c *Command) RunWithStderr(ctx context.Context) RunStdError

func (*Command) Start 

func (c *Command) Start(ctx context.Context) (retErr error)

func (*Command) StartWithStderr 

func (c *Command) StartWithStderr(ctx context.Context) RunStdError

func (*Command) Wait 

func (c *Command) Wait() error

func (*Command) WaitWithStderr 

func (c *Command) WaitWithStderr() RunStdError

func (*Command) WithDir 

func (c *Command) WithDir(dir string) *Command

func (*Command) WithEnv 

func (c *Command) WithEnv(env []string) *Command

func (*Command) WithParentCallerInfo 

func (c *Command) WithParentCallerInfo(optInfo ...string) *Command

WithParentCallerInfo can be used to set the caller info (usually function name) of the parent function of the caller. For most cases, "Run" family functions can get its caller info automatically But if you need to call "Run" family functions in a wrapper function: "FeatureFunc -> GeneralWrapperFunc -> RunXxx", then you can to call this function in GeneralWrapperFunc to set the caller info of FeatureFunc. The caller info can only be set once.

func (*Command) WithPipelineFunc 

func (c *Command) WithPipelineFunc(f func(ctx Context) error) *Command

WithPipelineFunc sets the pipeline function for the command. The pipeline function will be called in the Run / Wait function after the command is started successfully. The function can read/write from/to the command's stdio pipes (if any). The pipeline function can cancel (kill) the command by calling ctx.CancelPipeline before the command finishes. The returned error of Run / Wait can be joined errors from the pipeline function, context cause, and command exit error. Caller can get the pipeline function's error (if any) by UnwrapPipelineError.

func (*Command) WithStdinBytes 

func (c *Command) WithStdinBytes(stdin []byte) *Command

func (*Command) WithStdinCopy 

func (c *Command) WithStdinCopy(w io.Reader) *Command

WithStdinCopy and WithStdoutCopy are general functions that accept any io.Reader / io.Writer. In this case, Golang exec.Cmd will start new internal goroutines to do io.Copy between pipes and provided Reader/Writer. If the reader or writer is blocked and never returns, then the io.Copy won't finish, then exec.Cmd.Wait won't return, which may cause deadlocks. A typical deadlock example is: * `r,w:=io.Pipe(); cmd.Stdin=r; defer w.Close(); cmd.Run()`: the Run() will never return because stdin reader is blocked forever and w.Close() will never be called. If the reader/writer won't block forever (for example: read from a file or buffer), then these functions are safe to use.

func (*Command) WithStdoutBuffer 

func (c *Command) WithStdoutBuffer(w PipeBufferWriter) *Command

func (*Command) WithStdoutCopy 

func (c *Command) WithStdoutCopy(w io.Writer) *Command

func (*Command) WithTimeout 

func (c *Command) WithTimeout(timeout time.Duration) *Command

type Context 

type Context interface {
	context.Context

	// CancelPipeline is a helper function to cancel the command context (kill the command) with a specific error cause,
	// it returns the same error for convenience to break the PipelineFunc easily
	CancelPipeline(err error) error
}

type PipeBufferReader 

type PipeBufferReader interface {
	// Read should be used in the same goroutine as command's Wait
	// When Reader in one goroutine, command's Wait in another goroutine, then the command exits, the pipe will be closed:
	// * If the Reader goroutine reads faster, it will read all remaining data and then get io.EOF
	//   * But this io.EOF doesn't mean the Reader has gotten complete data, the data might still be corrupted
	// * If the Reader goroutine reads slower, it will get os.ErrClosed because the os.Pipe is closed ahead when the command exits
	//
	// When using 2 goroutines, no clear solution to distinguish these two cases or make Reader knows whether the data is complete
	// It should avoid using Reader in a different goroutine than the command if the Read error needs to be handled.
	Read(p []byte) (n int, err error)
	Bytes() []byte
}

type PipeBufferWriter 

type PipeBufferWriter interface {
	Write(p []byte) (n int, err error)
	Bytes() []byte
}

type PipeReader 

type PipeReader interface {
	io.ReadCloser
	// contains filtered or unexported methods
}

type PipeWriter 

type PipeWriter interface {
	io.WriteCloser
	// contains filtered or unexported methods
}

type RunStdError 

type RunStdError interface {
	error
	Unwrap() error
	Stderr() string
}

type TrustedCmdArgs 

type TrustedCmdArgs []internal.CmdArg

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

func ToTrustedCmdArgs 

func ToTrustedCmdArgs(args []string) TrustedCmdArgs

ToTrustedCmdArgs converts a list of strings (trusted as argument) to TrustedCmdArgs In most cases, it shouldn't be used. Use NewCommand().AddXxx() function instead

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.