subprocess is a Go library that returns standard output, standard error, and exit status code data from newly spawned processes on Linux, macOS, and Windows platforms. It was inspired by the Python subprocess standard library module.
The subprocess library API is versioned under the SemVer specification.
The subprocess package does not include external dependencies. It is built with the Go standard library.
Install the subprocess library locally for testing and development use with the following command:
go get gopkg.in/go-rillas/subprocess.v1
subprocess exposes two public functions and a public struct with standard output, standard error, and exit status code data from executable files. Full API documentation is available on GoDoc.
package main
import (
"gopkg.in/go-rillas/subprocess.v1"
)
The subprocess package defines the Response
public data type with standard output, standard error, and exit status code fields. This is populated and returned to the calling code when you run an executable file with the public functions that are available in the subprocess package.
type Response struct {
StdOut string
StdErr string
ExitCode int
}
func Run(executable string, args ...string) Response
The Run()
function runs an executable file with optional arguments and returns the standard output, standard error, and exit status code data in a Response
struct. Include one or more arguments to the executable as additional function parameters.
package main
import (
"fmt"
"gopkg.in/go-rillas/subprocess.v1"
)
func main() {
response := Run("ls", "-l")
// print the standard output stream data
fmt.Printf("%s", response.StdOut)
// print the standard error stream data
fmt.Printf("%s", response.StdErr)
// print the exit status code integer value
fmt.Printf("%d", response.ExitCode)
}
package main
import (
"fmt"
"gopkg.in/go-rillas/subprocess.v1"
)
func main() {
response := Run("dir", "/AD")
// print the standard output stream data
fmt.Printf("%s", response.StdOut)
// print the standard error stream data
fmt.Printf("%s", response.StdErr)
// print the exit status code integer value
fmt.Printf("%d", response.ExitCode)
}
func RunShell(shell string, shellflag string, command ...string) Response
The RunShell()
function runs an executable file with a shell and returns the standard output, standard error, and exit status code data in a Response
struct. The default shell for Linux and macOS platforms is /bin/sh
. The default shell for Windows is the cmd.exe
command prompt. Modify the shell by defining the shell
function parameter. A shell flag is included to indicate that the argument that follows is to be executed by the shell. The default flag on macOS and Linux platforms is -c
. On Windows, this is /C
. Modify the flag by defining the shellflag
parameter. Define the command to be executed as one or more parameters at the end of the function call.
package main
import (
"fmt"
"gopkg.in/go-rillas/subprocess.v1"
)
func main() {
response := RunShell("", "", "ls", "-l")
// print the standard output stream data
fmt.Printf("%s", response.StdOut)
// print the standard error stream data
fmt.Printf("%s", response.StdErr)
// print the exit status code integer value
fmt.Printf("%d", response.ExitCode)
}
package main
import (
"fmt"
"gopkg.in/go-rillas/subprocess.v1"
)
func main() {
response := RunShell("", "", "dir", "/AD")
// print the standard output stream data
fmt.Printf("%s", response.StdOut)
// print the standard error stream data
fmt.Printf("%s", response.StdErr)
// print the exit status code integer value
fmt.Printf("%d", response.ExitCode)
}
package main
import (
"fmt"
"gopkg.in/go-rillas/subprocess.v1"
)
func main() {
response := RunShell("/usr/local/bin/zsh", "", "ls", "-l")
// print the standard output stream data
fmt.Printf("%s", response.StdOut)
// print the standard error stream data
fmt.Printf("%s", response.StdErr)
// print the exit status code integer value
fmt.Printf("%d", response.ExitCode)
}
package main
import (
"fmt"
"gopkg.in/go-rillas/subprocess.v1"
)
func main() {
response := RunShell("bash", "-c", "ls", "-l")
// print the standard output stream data
fmt.Printf("%s", response.StdOut)
// print the standard error stream data
fmt.Printf("%s", response.StdErr)
// print the exit status code integer value
fmt.Printf("%d", response.ExitCode)
}
Contributions to the project are welcomed. Please submit changes in a pull request on the Github repository.
climock is a dependency that must be installed manually for the execution of subprocess package tests.
Install climock
with:
$ go get -u github.com/chrissimpkins/climock
You can then execute source code unit tests and obtain source code coverage data locally by downloading the source repository and executing the following command in the root of the source repository:
$ go test -v -cover ./...
Go must be installed on your system to execute this command.
We test the subprocess package with Semaphore CI (Linux) and Appveyor CI (Windows). You may view the test results following the most recent commit (including commits proposed through a pull request) using those links.
The subprocess library was inspired by the Python standard library subprocess module. Source code for the exit status code retrieval was based on source discussed in the Stack Overflow posts here and here. A big thanks to Michael (@texhex) and JM (@jublo) for their input and feedback on the Windows platform support.
The subprocess library is licensed under the MIT license.