Documentation
¶
Overview ¶
Package sh provides tools to build and manipulate shell commands.
Index ¶
- Constants
- func Command(cmd string, args ...string) string
- func Quote(s string) string
- func Shell(command string) string
- func ShellWith(shell, command string) string
- type CommandBuilder
- func (c CommandBuilder) AppendErrToFile(file string) CommandBuilder
- func (c CommandBuilder) AppendOutToFile(file string) CommandBuilder
- func (c CommandBuilder) Arg(arg string) CommandBuilder
- func (c CommandBuilder) Args(args ...string) CommandBuilder
- func (c CommandBuilder) ErrToFile(file string) CommandBuilder
- func (c CommandBuilder) ErrToNull() CommandBuilder
- func (c CommandBuilder) ErrToOut() CommandBuilder
- func (c CommandBuilder) OutToFile(file string) CommandBuilder
- func (c CommandBuilder) OutToNull() CommandBuilder
- func (c CommandBuilder) Pipe(cmd string, args ...string) CommandBuilder
- func (c CommandBuilder) Raw(arg string) CommandBuilder
- func (c CommandBuilder) String() string
Examples ¶
Constants ¶
const DefaultShell = "/bin/sh"
DefaultShell is the shell rig uses to run commands on non-Windows hosts. An absolute path is used on purpose: the whole point of imposing a shell is to not depend on the remote environment, and that includes PATH.
Variables ¶
This section is empty.
Functions ¶
func Command ¶
Command returns a shell escaped command string.
Example:
c.Exec(sh.Command("echo", "hello world"))
// resulting command: echo 'hello world'
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
fmt.Println(sh.Command("echo", "foo bar"))
}
Output: echo 'foo bar'
Example (Builder) ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").ErrToNull().OutToFile("file").Pipe("grep").Args("-q", "foo bar")
fmt.Println(cmd.String())
}
Output: echo foo 2>/dev/null >file | grep -q 'foo bar'
func Quote ¶
Quote returns a shell escaped string. This is a wrapper around shellescape.Quote and it is here to avoid importing shellescape separately.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
fmt.Println(sh.Quote("foo bar"))
}
Output: 'foo bar'
func Shell ¶ added in v2.2.0
Shell returns the command wrapped in an explicit invocation of DefaultShell:
sh.Shell("echo foo | tee bar")
// resulting command: /bin/sh -c -- 'echo foo | tee bar'
Use this when a command must be interpreted by a POSIX shell, either because it is a compound expression handed to something that execs directly (like sudo) or because whatever runs it may not be a POSIX shell, such as a remote user's fish login shell.
This is the one place a rig command is quoted for a shell nobody chose, so the quoting comes from shellescape.QuoteForLoginShell, which covers POSIX shells and fish. A csh login shell can still reject a command containing ! or an embedded newline.
Types ¶
type CommandBuilder ¶
type CommandBuilder string
CommandBuilder is a builder for shell commands. It is based on string and can be converted to one using string(CommandBuilder("foo")) or calling the String method.
func (CommandBuilder) AppendErrToFile ¶
func (c CommandBuilder) AppendErrToFile(file string) CommandBuilder
AppendErrToFile appends the command's stderr to a file.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").AppendErrToFile("file")
fmt.Println(cmd.String())
}
Output: echo foo 2>>file
func (CommandBuilder) AppendOutToFile ¶
func (c CommandBuilder) AppendOutToFile(file string) CommandBuilder
AppendOutToFile appends the command's stdout to a file.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").AppendOutToFile("file")
fmt.Println(cmd.String())
}
Output: echo foo >>file
func (CommandBuilder) Arg ¶
func (c CommandBuilder) Arg(arg string) CommandBuilder
Arg adds an argument to the command. The argument is shell escaped.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").Arg("bar baz")
fmt.Println(cmd.String())
}
Output: echo foo 'bar baz'
func (CommandBuilder) Args ¶
func (c CommandBuilder) Args(args ...string) CommandBuilder
Args adds multiple arguments to the command. The arguments are shell escaped.
func (CommandBuilder) ErrToFile ¶
func (c CommandBuilder) ErrToFile(file string) CommandBuilder
ErrToFile redirects the command's stderr to a file.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").ErrToFile("file")
fmt.Println(cmd.String())
}
Output: echo foo 2>file
func (CommandBuilder) ErrToNull ¶
func (c CommandBuilder) ErrToNull() CommandBuilder
ErrToNull redirects the command's stderr to /dev/null.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").ErrToNull()
fmt.Println(cmd.String())
}
Output: echo foo 2>/dev/null
func (CommandBuilder) ErrToOut ¶
func (c CommandBuilder) ErrToOut() CommandBuilder
ErrToOut redirects the command's stderr to stdout.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").ErrToOut()
fmt.Println(cmd.String())
}
Output: echo foo 2>&1
func (CommandBuilder) OutToFile ¶
func (c CommandBuilder) OutToFile(file string) CommandBuilder
OutToFile redirects the command's stdout to a file.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").OutToFile("file")
fmt.Println(cmd.String())
}
Output: echo foo >file
func (CommandBuilder) OutToNull ¶
func (c CommandBuilder) OutToNull() CommandBuilder
OutToNull redirects the command's stdout to /dev/null.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").OutToNull()
fmt.Println(cmd.String())
}
Output: echo foo >/dev/null
func (CommandBuilder) Pipe ¶
func (c CommandBuilder) Pipe(cmd string, args ...string) CommandBuilder
Pipe the command to another command. The target command is shell escaped.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("echo").Arg("foo").Pipe("grep", "-q").Arg("foo")
fmt.Println(cmd.String())
}
Output: echo foo | grep -q foo
func (CommandBuilder) Raw ¶
func (c CommandBuilder) Raw(arg string) CommandBuilder
Raw adds a raw string to the command without shell escaping. This is needed when you want to use shell operators, globbing or variables.
Example ¶
package main
import (
"fmt"
"github.com/k0sproject/rig/v2/sh"
)
func main() {
cmd := sh.CommandBuilder("ls").Raw("**/*.go")
fmt.Println(cmd.String())
}
Output: ls **/*.go
func (CommandBuilder) String ¶
func (c CommandBuilder) String() string
String returns the command as a string.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package shellescape provides functions to escape strings for use in posix shell commands.
|
Package shellescape provides functions to escape strings for use in posix shell commands. |