From 3e2504382508abf2615e6925e13d0d19e003604e Mon Sep 17 00:00:00 2001 From: Justin Date: Mon, 23 Oct 2023 19:47:07 -0400 Subject: [PATCH] docs: auto-generate docs (#651) Issue #, if available: *Description of changes:* - Add `finch gen-docs generate` command, which can be used to generate documentation - This actually runs all of the commands, so a finch vm needs to be running - This is because many of the commands shell out to nerdctl inside of a Linux VM, so simply leveraging cobra's built-in documentation generation won't work - Actually running the commands and then parsing the output into a markdown file is... kinda hacky, so this might break from time to time - This only works for top-level nerdctl commands right now, because those are the only commands that finch "knows" about. Meaning, while `finch volume create` is a command, with it's own usage information, it won't have a page here. The doc for `finch volume` does reference its subcommands, however. *Testing done:* - TODO - [x] unit tests - [x] I've reviewed the guidance in CONTRIBUTING.md #### License Acceptance By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license. --------- Signed-off-by: Justin Alvarez --- .markdownlintignore | 6 + cmd/finch/doc.TEMPLATE | 38 ++++ cmd/finch/gen_docs.go | 235 ++++++++++++++++++++++ cmd/finch/gen_docs_test.go | 180 +++++++++++++++++ cmd/finch/main.go | 1 + cmd/finch/main_test.go | 4 +- docs/cmd/finch_build.md | 32 +++ docs/cmd/finch_builder.md | 21 ++ docs/cmd/finch_commit.md | 17 ++ docs/cmd/finch_completion_bash.md | 25 +++ docs/cmd/finch_completion_fish.md | 24 +++ docs/cmd/finch_completion_powershell.md | 21 ++ docs/cmd/finch_completion_zsh.md | 27 +++ docs/cmd/finch_compose.md | 48 +++++ docs/cmd/finch_container.md | 40 ++++ docs/cmd/finch_cp.md | 18 ++ docs/cmd/finch_create.md | 95 +++++++++ docs/cmd/finch_events.md | 14 ++ docs/cmd/finch_exec.md | 21 ++ docs/cmd/finch_help.md | 14 ++ docs/cmd/finch_history.md | 16 ++ docs/cmd/finch_image.md | 32 +++ docs/cmd/finch_images.md | 31 +++ docs/cmd/finch_info.md | 15 ++ docs/cmd/finch_inspect.md | 16 ++ docs/cmd/finch_kill.md | 14 ++ docs/cmd/finch_load.md | 16 ++ docs/cmd/finch_login.md | 16 ++ docs/cmd/finch_logout.md | 13 ++ docs/cmd/finch_logs.md | 23 +++ docs/cmd/finch_network.md | 23 +++ docs/cmd/finch_pause.md | 13 ++ docs/cmd/finch_port.md | 13 ++ docs/cmd/finch_ps.md | 21 ++ docs/cmd/finch_pull.md | 24 +++ docs/cmd/finch_push.md | 25 +++ docs/cmd/finch_restart.md | 14 ++ docs/cmd/finch_rm.md | 15 ++ docs/cmd/finch_rmi.md | 15 ++ docs/cmd/finch_run.md | 96 +++++++++ docs/cmd/finch_save.md | 16 ++ docs/cmd/finch_start.md | 15 ++ docs/cmd/finch_stats.md | 17 ++ docs/cmd/finch_stop.md | 14 ++ docs/cmd/finch_support-bundle_generate.md | 15 ++ docs/cmd/finch_system.md | 21 ++ docs/cmd/finch_tag.md | 13 ++ docs/cmd/finch_top.md | 13 ++ docs/cmd/finch_unpause.md | 13 ++ docs/cmd/finch_update.md | 26 +++ docs/cmd/finch_version.md | 13 ++ docs/cmd/finch_vm_init.md | 13 ++ docs/cmd/finch_vm_remove.md | 14 ++ docs/cmd/finch_vm_start.md | 13 ++ docs/cmd/finch_vm_status.md | 13 ++ docs/cmd/finch_vm_stop.md | 14 ++ docs/cmd/finch_volume.md | 23 +++ docs/cmd/finch_wait.md | 13 ++ pkg/mocks/gen_docs_system_deps.go | 80 ++++++++ pkg/system/stdlib.go | 8 + pkg/system/system.go | 10 + 61 files changed, 1707 insertions(+), 2 deletions(-) create mode 100644 .markdownlintignore create mode 100644 cmd/finch/doc.TEMPLATE create mode 100644 cmd/finch/gen_docs.go create mode 100644 cmd/finch/gen_docs_test.go create mode 100644 docs/cmd/finch_build.md create mode 100644 docs/cmd/finch_builder.md create mode 100644 docs/cmd/finch_commit.md create mode 100644 docs/cmd/finch_completion_bash.md create mode 100644 docs/cmd/finch_completion_fish.md create mode 100644 docs/cmd/finch_completion_powershell.md create mode 100644 docs/cmd/finch_completion_zsh.md create mode 100644 docs/cmd/finch_compose.md create mode 100644 docs/cmd/finch_container.md create mode 100644 docs/cmd/finch_cp.md create mode 100644 docs/cmd/finch_create.md create mode 100644 docs/cmd/finch_events.md create mode 100644 docs/cmd/finch_exec.md create mode 100644 docs/cmd/finch_help.md create mode 100644 docs/cmd/finch_history.md create mode 100644 docs/cmd/finch_image.md create mode 100644 docs/cmd/finch_images.md create mode 100644 docs/cmd/finch_info.md create mode 100644 docs/cmd/finch_inspect.md create mode 100644 docs/cmd/finch_kill.md create mode 100644 docs/cmd/finch_load.md create mode 100644 docs/cmd/finch_login.md create mode 100644 docs/cmd/finch_logout.md create mode 100644 docs/cmd/finch_logs.md create mode 100644 docs/cmd/finch_network.md create mode 100644 docs/cmd/finch_pause.md create mode 100644 docs/cmd/finch_port.md create mode 100644 docs/cmd/finch_ps.md create mode 100644 docs/cmd/finch_pull.md create mode 100644 docs/cmd/finch_push.md create mode 100644 docs/cmd/finch_restart.md create mode 100644 docs/cmd/finch_rm.md create mode 100644 docs/cmd/finch_rmi.md create mode 100644 docs/cmd/finch_run.md create mode 100644 docs/cmd/finch_save.md create mode 100644 docs/cmd/finch_start.md create mode 100644 docs/cmd/finch_stats.md create mode 100644 docs/cmd/finch_stop.md create mode 100644 docs/cmd/finch_support-bundle_generate.md create mode 100644 docs/cmd/finch_system.md create mode 100644 docs/cmd/finch_tag.md create mode 100644 docs/cmd/finch_top.md create mode 100644 docs/cmd/finch_unpause.md create mode 100644 docs/cmd/finch_update.md create mode 100644 docs/cmd/finch_version.md create mode 100644 docs/cmd/finch_vm_init.md create mode 100644 docs/cmd/finch_vm_remove.md create mode 100644 docs/cmd/finch_vm_start.md create mode 100644 docs/cmd/finch_vm_status.md create mode 100644 docs/cmd/finch_vm_stop.md create mode 100644 docs/cmd/finch_volume.md create mode 100644 docs/cmd/finch_wait.md create mode 100644 pkg/mocks/gen_docs_system_deps.go diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 000000000..30628358c --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,6 @@ +deps/ +# Since the current documentation generation works by just capturing stdout, we don't do any post processing +# The completion files have issues with code block style +docs/cmd/*completion*.md +# finch_logs.md has issues with the list not being surrounded by newlines +docs/cmd/finch_logs.md diff --git a/cmd/finch/doc.TEMPLATE b/cmd/finch/doc.TEMPLATE new file mode 100644 index 000000000..9a0c7c264 --- /dev/null +++ b/cmd/finch/doc.TEMPLATE @@ -0,0 +1,38 @@ +# {{ .CmdPath }} + +{{if gt (len .Description) 0}}{{ .Description }} + +{{end}}{{if gt (len .Properties) 0}}## Properties + +{{.Properties}} + +{{end}}```text +{{ .Usage }} +```{{if gt (len .Aliases) 0}} + +## Aliases + +{{.Aliases}} +{{end}}{{if gt (len .Examples) 0}} + +## Examples + +{{.Examples}} +{{end}}{{if gt (len .Commands) 0}} + +## Commands + +```text +{{ .Commands }} +```{{end}}{{if gt (len .Options) 0}} + +## Options + +```text +{{ .Options }} +```{{end}}{{if gt (len .SeeAlso) 0}} + +## SEE ALSO + +{{ .SeeAlso }} +{{end}} diff --git a/cmd/finch/gen_docs.go b/cmd/finch/gen_docs.go new file mode 100644 index 000000000..4aa0f9330 --- /dev/null +++ b/cmd/finch/gen_docs.go @@ -0,0 +1,235 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 + +package main + +import ( + "bytes" + _ "embed" + "fmt" + "io" + "os" + "path/filepath" + "regexp" + "strings" + "text/template" + + "github.com/spf13/afero" + "github.com/spf13/cobra" + + "github.com/runfinch/finch/pkg/flog" + "github.com/runfinch/finch/pkg/system" +) + +// GenDocsSystemDeps contains the system dependencies for newGenDocsCommand. +// +//go:generate mockgen -copyright_file=../../copyright_header -destination=../../pkg/mocks/gen_docs_system_deps.go -package=mocks -mock_names GenDocsSystemDeps=GenDocsSystemDeps -source=gen_docs.go GenDocsSystemDeps +type GenDocsSystemDeps interface { + system.PipeGetter + system.StdoutGetter + system.StdoutSetter +} + +func newGenDocsCommand( + rootCmd *cobra.Command, + logger flog.Logger, + fs afero.Fs, + deps GenDocsSystemDeps, +) *cobra.Command { + genDocsCommand := &cobra.Command{ + Use: "gen-docs", + Short: "Document generation", + } + genDocsCommand.AddCommand( + newGenDocsGenerateCommand(rootCmd, logger, fs, deps), + ) + return genDocsCommand +} + +func newGenDocsGenerateCommand( + rootCmd *cobra.Command, + logger flog.Logger, + fs afero.Fs, + deps GenDocsSystemDeps, +) *cobra.Command { + genDocsGenerateCommand := &cobra.Command{ + Use: "generate", + Args: cobra.NoArgs, + Hidden: true, + Short: "Generate Finch docs", + RunE: newGenDocsGenerateAction(rootCmd, logger, fs, deps).runAdapter, + } + + genDocsGenerateCommand.Flags().StringP("path", "p", "", "Doc output directory") + // Ignore error since we check if the flag is set anyway + _ = genDocsGenerateCommand.MarkFlagRequired("path") + + return genDocsGenerateCommand +} + +type genDocsAction struct { + rootCmd *cobra.Command + logger flog.Logger + fs afero.Fs + deps GenDocsSystemDeps +} + +func newGenDocsGenerateAction( + rootCmd *cobra.Command, + logger flog.Logger, + fs afero.Fs, + deps GenDocsSystemDeps, +) *genDocsAction { + return &genDocsAction{ + rootCmd: rootCmd, + logger: logger, + deps: deps, + fs: fs, + } +} + +func (gd *genDocsAction) runAdapter(cmd *cobra.Command, _ []string) error { + path, err := cmd.Flags().GetString("path") + if err != nil { + return fmt.Errorf("failed to get required parameter 'path': %w", err) + } + return gd.run(path) +} + +func (gd *genDocsAction) run(outDir string) error { + return gd.captureHelpOutput(gd.rootCmd, outDir) +} + +func (gd *genDocsAction) captureHelpOutput(cmd *cobra.Command, outDir string) error { + for _, c := range cmd.Commands() { + if err := gd.captureHelpOutput(c, outDir); err != nil { + return fmt.Errorf("error while generating docs for %s: %w", c.CommandPath(), err) + } + } + + if !cmd.Runnable() || cmd.Hidden { + return nil + } + + gd.logger.Infof("Creating doc for command: %s", cmd.CommandPath()) + + baseName := strings.ReplaceAll(cmd.CommandPath(), " ", "_") + ".md" + fileName := filepath.Clean(filepath.Join(outDir, baseName)) + f, err := gd.fs.OpenFile(fileName, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0o666) + if err != nil { + return fmt.Errorf("error while creating out file %q: %w", fileName, err) + } + + // redirect Stdout to pipe + rescueStdout := gd.deps.Stdout() + r, w, err := gd.deps.Pipe() + if err != nil { + return fmt.Errorf("error while creating pipe to capture stdout: %w", err) + } + gd.deps.SetStdout(w) + + rootCmd := cmd.Root() + + // everything except the initial `finch` + args := strings.Split(cmd.CommandPath(), " ")[1:] + args = append(args, "--help") + rootCmd.SetArgs(args) + // rootCmd.SetOutput() would work for all "default finch" commands, but doesn't work + // for the nerdctl commands. Getting it to work would remove the need to capture all Stdout. + if err := rootCmd.Execute(); err != nil { + // This is pretty much impossible because cobra checks if --help is set and if it is it doesn't + // actually run the command. + // https://github.com/spf13/cobra/blob/main/command.go#L1096-L1099 + return fmt.Errorf("error while executing command (args=%v): %w", args, err) + } + gd.deps.SetStdout(rescueStdout) + + _ = w.Close() + helpText, err := io.ReadAll(r) + if err != nil { + return fmt.Errorf("error while reading stdout from pipe: %w", err) + } + + // Link to parent command page if parent command is also runnable. + // For example, if `finch vm` and `finch vm init` both had their own Run/RunE methods defined, + // finch vm init's documentation page would link to finch vm's page. + // If this condition is not met, then there is no "SEE ALSO" section. + seeAlso := "" + if cmd.HasParent() && cmd.Parent().Runnable() { + parentName := cmd.Parent().CommandPath() + parentDocFile := parentName + ".md" + parentDocFile = strings.ReplaceAll(parentDocFile, " ", "_") + parentShortDescription := cmd.Parent().Short + seeAlso = fmt.Sprintf("* [%s](%s)\t - %s\n", parentName, parentDocFile, parentShortDescription) + } + + mdOut, err := convertToMarkdown(cmd.CommandPath(), seeAlso, string(helpText)) + if err != nil { + return fmt.Errorf("error while converting docs to markdown: %w", err) + } + + if _, err := f.WriteString(mdOut); err != nil { + return fmt.Errorf("error while writing docs to file (%q): %w", f.Name(), err) + } + + _ = f.Close() + + return nil +} + +//go:embed doc.TEMPLATE +var docTmpl string + +type docTmplOpts struct { + CmdPath string + Description string + Properties string + Usage string + Aliases string + Examples string + Commands string + Options string + SeeAlso string +} + +func convertToMarkdown(cmdPath, seeAlso, helpText string) (string, error) { + t := template.Must(template.New("docTmpl").Parse(docTmpl)) + opts := docTmplOpts{ + CmdPath: cmdPath, + } + + opts.SeeAlso = seeAlso + + // Assume that everything up until "header section" (i.e. `Usage:\n`) is a description + re := regexp.MustCompile(`(?msU)^(.*)[A-Z]\w*:\s`) + matches := re.FindStringSubmatch(helpText) + // Take the last index (if no match, 0 or if match, 1) as the description. + // This handles the rare case in where the only help info is a description. + opts.Description = strings.TrimSpace(matches[len(matches)-1]) + + // The rest of the fields are treated as optional. + // A reference of all fields and how they may appear in help out put can + // be found here: https://github.com/spf13/cobra/blob/v1.7.0/command.go#L539-L568 + opts.Properties = tryExtractField(helpText, "Properties") + opts.Usage = tryExtractField(helpText, "Usage") + opts.Aliases = tryExtractField(helpText, "Aliases") + opts.Examples = tryExtractField(helpText, "Examples") + opts.Commands = tryExtractField(helpText, "Commands") + opts.Options = tryExtractField(helpText, "Flags") + + var tmpl bytes.Buffer + if err := t.Execute(&tmpl, opts); err != nil { + return "", err + } + + return tmpl.String(), nil +} + +func tryExtractField(helpString, fieldName string) string { + re := regexp.MustCompile(fmt.Sprintf(`(?smU)^%s:\s(.*)^\s?$`, fieldName)) + matches := re.FindStringSubmatch(strings.TrimSpace(helpString)) + if len(matches) == 2 { + return strings.TrimSuffix(strings.TrimSuffix(matches[1], " "), "\n") + } + return "" +} diff --git a/cmd/finch/gen_docs_test.go b/cmd/finch/gen_docs_test.go new file mode 100644 index 000000000..5d5905127 --- /dev/null +++ b/cmd/finch/gen_docs_test.go @@ -0,0 +1,180 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 + +package main + +import ( + "fmt" + "os" + "testing" + + "github.com/spf13/afero" + "github.com/spf13/cobra" + + "github.com/runfinch/finch/pkg/mocks" + + "github.com/golang/mock/gomock" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestNewGenDocsCommand(t *testing.T) { + t.Parallel() + + ctrl := gomock.NewController(t) + logger := mocks.NewLogger(ctrl) + mFs := afero.NewMemMapFs() + deps := mocks.NewGenDocsSystemDeps(ctrl) + cmd := newGenDocsCommand(&cobra.Command{}, logger, mFs, deps) + assert.Equal(t, cmd.Name(), "gen-docs") +} + +func TestNewGenDocsGenerateCommand(t *testing.T) { + t.Parallel() + + ctrl := gomock.NewController(t) + logger := mocks.NewLogger(ctrl) + mFs := afero.NewMemMapFs() + deps := mocks.NewGenDocsSystemDeps(ctrl) + cmd := newGenDocsGenerateCommand(&cobra.Command{}, logger, mFs, deps) + assert.Equal(t, cmd.Name(), "generate") +} + +var codeBlock = "```" + +//nolint:paralleltest // This function manipulates stdout +func TestGenDocsAction_runAdapter(t *testing.T) { + testCases := []struct { + name string + cmd func(t *testing.T) *cobra.Command + mockSvc func( + ctrl *gomock.Controller, + t *testing.T, + logger *mocks.Logger, + mFs afero.Fs, + deps *mocks.GenDocsSystemDeps, + stdout *os.File, + ) + want error + postRunCheck func(t *testing.T, fs afero.Fs) + }{ + { + name: "path is set and exists", + cmd: func(t *testing.T) *cobra.Command { + c := &cobra.Command{ + Use: "test-command", + Run: func(_ *cobra.Command, _ []string) {}, + } + c.Flags().StringP("path", "p", "", "Doc output directory") + require.NoError(t, c.Flags().Set("path", "outDir")) + require.NoError(t, c.Execute()) + return c + }, + mockSvc: func( + ctrl *gomock.Controller, + t *testing.T, + logger *mocks.Logger, + mFs afero.Fs, + deps *mocks.GenDocsSystemDeps, + stdout *os.File, + ) { + require.NoError(t, mFs.Mkdir("outDir", 0o666)) + logger.EXPECT().Infof("Creating doc for command: %s", "test-command") + // Hijack stdout before the command does and replace it with a pipe + stdoutR, stdoutW, err := os.Pipe() + require.NoError(t, err) + os.Stdout = stdoutW + deps.EXPECT().Stdout().Return(os.Stdout) + deps.EXPECT().Pipe().Return(stdoutR, stdoutW, nil) + deps.EXPECT().SetStdout(stdoutW) + deps.EXPECT().SetStdout(os.Stdout) + }, + want: nil, + postRunCheck: func(t *testing.T, fs afero.Fs) { + buf, err := afero.ReadFile(fs, "outDir/test-command.md") + require.NoError(t, err) + require.Equal(t, string(buf), fmt.Sprintf(`# test-command + +%stext + test-command [flags] +%s +`, codeBlock, codeBlock)) + }, + }, + { + name: "path is set and exists but can't create pipe", + cmd: func(t *testing.T) *cobra.Command { + c := &cobra.Command{ + Use: "test-command", + Run: func(_ *cobra.Command, _ []string) {}, + } + c.Flags().StringP("path", "p", "", "Doc output directory") + require.NoError(t, c.Flags().Set("path", "outDir")) + require.NoError(t, c.Execute()) + return c + }, + mockSvc: func( + ctrl *gomock.Controller, + t *testing.T, + logger *mocks.Logger, + mFs afero.Fs, + deps *mocks.GenDocsSystemDeps, + stdout *os.File, + ) { + require.NoError(t, mFs.Mkdir("outDir", 0o666)) + logger.EXPECT().Infof("Creating doc for command: %s", "test-command") + stdoutR, stdoutW, err := os.Pipe() + require.NoError(t, err) + deps.EXPECT().Stdout().Return(stdoutW) + deps.EXPECT().Pipe().Return(stdoutR, stdoutW, fmt.Errorf("can't create pipe")) + }, + want: fmt.Errorf("error while creating pipe to capture stdout: %w", fmt.Errorf("can't create pipe")), + postRunCheck: func(t *testing.T, fs afero.Fs) { + buf, err := afero.ReadFile(fs, "outDir/test-command.md") + require.NoError(t, err) + require.Equal(t, buf, []byte(``)) + }, + }, + { + name: "path is set and command is not runnable", + cmd: func(t *testing.T) *cobra.Command { + c := &cobra.Command{ + Use: "test-command", + } + c.Flags().StringP("path", "p", "", "Doc output directory") + require.NoError(t, c.Flags().Set("path", "outDir")) + require.NoError(t, c.Execute()) + return c + }, + mockSvc: func( + ctrl *gomock.Controller, + t *testing.T, + logger *mocks.Logger, + mFs afero.Fs, + deps *mocks.GenDocsSystemDeps, + stdout *os.File, + ) { + }, + want: nil, + postRunCheck: func(t *testing.T, fs afero.Fs) { + }, + }, + } + + //nolint:paralleltest // This function manipulates stdout + for _, tc := range testCases { + tc := tc + t.Run(tc.name, func(t *testing.T) { + ctrl := gomock.NewController(t) + logger := mocks.NewLogger(ctrl) + mFs := afero.NewMemMapFs() + deps := mocks.NewGenDocsSystemDeps(ctrl) + rescueStdout := os.Stdout + tc.mockSvc(ctrl, t, logger, mFs, deps, os.Stdout) + got := newGenDocsGenerateAction(tc.cmd(t), logger, mFs, deps).runAdapter(tc.cmd(t), nil) + os.Stdout = rescueStdout + assert.Equal(t, tc.want, got) + tc.postRunCheck(t, mFs) + }) + } +} diff --git a/cmd/finch/main.go b/cmd/finch/main.go index 1c95ca958..57d6079a7 100644 --- a/cmd/finch/main.go +++ b/cmd/finch/main.go @@ -107,6 +107,7 @@ var newApp = func(logger flog.Logger, fp path.Finch, fs afero.Fs, fc *config.Fin newVersionCommand(lcc, logger, stdOut), virtualMachineCommands(logger, fp, lcc, ecc, fs, fc), newSupportBundleCommand(logger, supportBundleBuilder, lcc), + newGenDocsCommand(rootCmd, logger, fs, system.NewStdLib()), ) rootCmd.AddCommand(allCommands...) diff --git a/cmd/finch/main_test.go b/cmd/finch/main_test.go index 43df113a7..0b03c5e9e 100644 --- a/cmd/finch/main_test.go +++ b/cmd/finch/main_test.go @@ -138,8 +138,8 @@ func TestNewApp(t *testing.T) { assert.Equal(t, cmd.Version, version.Version) assert.Equal(t, cmd.SilenceUsage, true) assert.Equal(t, cmd.SilenceErrors, true) - // confirm the number of command, comprised of nerdctl commands + finch commands (version, vm, support-bundle) - assert.Equal(t, len(cmd.Commands()), len(nerdctlCmds)+3) + // confirm the number of command, comprised of nerdctl commands + finch commands + assert.Equal(t, len(cmd.Commands()), len(nerdctlCmds)+4) // PersistentPreRunE should set logger level to debug if the debug flag exists. mockCmd := &cobra.Command{} diff --git a/docs/cmd/finch_build.md b/docs/cmd/finch_build.md new file mode 100644 index 000000000..02213dfa7 --- /dev/null +++ b/docs/cmd/finch_build.md @@ -0,0 +1,32 @@ +# finch build + +Build an image from a Dockerfile. Needs buildkitd to be running. +If Dockerfile is not present and -f is not specified, it will look for Containerfile and build with it. + +```text +finch build [flags] PATH +``` + +## Options + +```text + --build-arg stringArray Set build-time variables + --buildkit-host string BuildKit address [$BUILDKIT_HOST] (default "unix:///run/buildkit/buildkitd.sock") + --cache-from stringArray External cache sources (eg. user/app:cache, type=local,src=path/to/dir) + --cache-to stringArray Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) + -f, --file string Name of the Dockerfile + -h, --help help for build + --iidfile string Write the image ID to the file + --label stringArray Set metadata for an image + --network string Set type of network for build (format:network=default|none|host) (default "default") + --no-cache Do not use cache when building the image + -o, --output string Output destination (format: type=local,dest=path) + --platform strings Set target platform for build (e.g., "amd64", "arm64") + --progress string Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto") + -q, --quiet Suppress the build output and print image ID on success + --rm Remove intermediate containers after a successful build (default true) + --secret stringArray Secret file to expose to the build: id=mysecret,src=/local/secret + --ssh stringArray SSH agent socket or keys to expose to the build (format: default|[=|[,]]) + -t, --tag stringArray Name and optionally a tag in the 'name:tag' format + --target string Set the target build stage to build +``` diff --git a/docs/cmd/finch_builder.md b/docs/cmd/finch_builder.md new file mode 100644 index 000000000..f184efa3e --- /dev/null +++ b/docs/cmd/finch_builder.md @@ -0,0 +1,21 @@ +# finch builder + +Manage builds + +```text +finch builder [flags] +``` + +## Commands + +```text + build Build an image from a Dockerfile. Needs buildkitd to be running. + debug Debug Dockerfile + prune Clean up BuildKit build cache +``` + +## Options + +```text + -h, --help help for builder +``` diff --git a/docs/cmd/finch_commit.md b/docs/cmd/finch_commit.md new file mode 100644 index 000000000..a1af07dcc --- /dev/null +++ b/docs/cmd/finch_commit.md @@ -0,0 +1,17 @@ +# finch commit + +Create a new image from a container's changes + +```text +finch commit [flags] CONTAINER REPOSITORY[:TAG] +``` + +## Options + +```text + -a, --author string Author (e.g., "finch contributor ") + -c, --change stringArray Apply Dockerfile instruction to the created image (supported directives: [CMD, ENTRYPOINT]) + -h, --help help for commit + -m, --message string Commit message + -p, --pause Pause container during commit (default true) +``` diff --git a/docs/cmd/finch_completion_bash.md b/docs/cmd/finch_completion_bash.md new file mode 100644 index 000000000..f23daf008 --- /dev/null +++ b/docs/cmd/finch_completion_bash.md @@ -0,0 +1,25 @@ +# finch completion bash + +Generate the autocompletion script for the bash shell. + +This script depends on the 'bash-completion' package. +If it is not installed already, you can install it via your OS's package manager. + +To load completions in your current shell session: + + source <(finch completion bash) + +To load completions for every new session, execute once: + +#### + +```text + finch completion bash +``` + +## Options + +```text + -h, --help help for bash + --no-descriptions disable completion descriptions +``` diff --git a/docs/cmd/finch_completion_fish.md b/docs/cmd/finch_completion_fish.md new file mode 100644 index 000000000..7bd00d9f9 --- /dev/null +++ b/docs/cmd/finch_completion_fish.md @@ -0,0 +1,24 @@ +# finch completion fish + +Generate the autocompletion script for the fish shell. + +To load completions in your current shell session: + + finch completion fish | source + +To load completions for every new session, execute once: + + finch completion fish > ~/.config/fish/completions/finch.fish + +You will need to start a new shell for this setup to take effect. + +```text + finch completion fish [flags] +``` + +## Options + +```text + -h, --help help for fish + --no-descriptions disable completion descriptions +``` diff --git a/docs/cmd/finch_completion_powershell.md b/docs/cmd/finch_completion_powershell.md new file mode 100644 index 000000000..2665ec6b4 --- /dev/null +++ b/docs/cmd/finch_completion_powershell.md @@ -0,0 +1,21 @@ +# finch completion powershell + +Generate the autocompletion script for powershell. + +To load completions in your current shell session: + + finch completion powershell | Out-String | Invoke-Expression + +To load completions for every new session, add the output of the above command +to your powershell profile. + +```text + finch completion powershell [flags] +``` + +## Options + +```text + -h, --help help for powershell + --no-descriptions disable completion descriptions +``` diff --git a/docs/cmd/finch_completion_zsh.md b/docs/cmd/finch_completion_zsh.md new file mode 100644 index 000000000..0ad834d53 --- /dev/null +++ b/docs/cmd/finch_completion_zsh.md @@ -0,0 +1,27 @@ +# finch completion zsh + +Generate the autocompletion script for the zsh shell. + +If shell completion is not already enabled in your environment you will need +to enable it. You can execute the following once: + + echo "autoload -U compinit; compinit" >> ~/.zshrc + +To load completions in your current shell session: + + source <(finch completion zsh) + +To load completions for every new session, execute once: + +#### + +```text + finch completion zsh [flags] +``` + +## Options + +```text + -h, --help help for zsh + --no-descriptions disable completion descriptions +``` diff --git a/docs/cmd/finch_compose.md b/docs/cmd/finch_compose.md new file mode 100644 index 000000000..1b6925380 --- /dev/null +++ b/docs/cmd/finch_compose.md @@ -0,0 +1,48 @@ +# finch compose + +Compose + +```text +finch compose [flags] COMMAND +``` + +## Commands + +```text + build Build or rebuild services + config Validate and view the Compose file + cp Copy files/folders between a service container and the local filesystem + create Creates containers for one or more services + down Remove containers and associated resources + exec Execute a command in a running container of the service + images List images used by created containers in services + kill Force stop service containers + logs Show logs of running containers + pause Pause all processes within containers of service(s). They can be unpaused with finch compose unpause + port Print the public port for a port binding + ps List containers of services + pull Pull service images + push Push service images + restart Restart containers of given (or all) services + rm Remove stopped service containers + run Run a one-off command on a service + start Start existing containers for service(s) + stop Stop running containers without removing them. + top Display the running processes of service containers + unpause Unpause all processes within containers of service(s). + up Create and start containers + version Show the Compose version information +``` + +## Options + +```text + --env-file string Specify an alternate environment file + -f, --f stringArray Alias of --file + --file stringArray Specify an alternate compose file + -h, --help help for compose + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --profile stringArray Specify a profile to enable + --project-directory string Specify an alternate working directory + -p, --project-name string Specify an alternate project name +``` diff --git a/docs/cmd/finch_container.md b/docs/cmd/finch_container.md new file mode 100644 index 000000000..3aa6daa16 --- /dev/null +++ b/docs/cmd/finch_container.md @@ -0,0 +1,40 @@ +# finch container + +Manage containers + +```text +finch container [flags] +``` + +## Commands + +```text + attach Attach stdin, stdout, and stderr to a running container. + commit Create a new image from a container's changes + cp Copy files/folders between a running container and the local filesystem. + create Create a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + exec Run a command in a running container + inspect Display detailed information on one or more containers. + kill Kill one or more running containers + logs Fetch the logs of a container. Expected to be used with 'finch run -d'. + ls List containers + pause Pause all processes within one or more containers + port List port mappings or a specific mapping for the container + prune Remove all stopped containers + rename rename a container + restart Restart one or more running containers + rm Remove one or more containers + run Run a command in a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + start Start one or more running containers + stats Display a live stream of container(s) resource usage statistics. + stop Stop one or more running containers + unpause Unpause all processes within one or more containers + update Update one or more running containers + wait Block until one or more containers stop, then print their exit codes. +``` + +## Options + +```text + -h, --help help for container +``` diff --git a/docs/cmd/finch_cp.md b/docs/cmd/finch_cp.md new file mode 100644 index 000000000..cc82dfb55 --- /dev/null +++ b/docs/cmd/finch_cp.md @@ -0,0 +1,18 @@ +# finch cp + +Copy files/folders between a running container and the local filesystem. +This command requires 'tar' to be installed on the host (not in the container). +Using GNU tar is recommended. +The path of the 'tar' binary can be specified with an environment variable '$TAR'. + +```text +finch cp [flags] CONTAINER:SRC_PATH DEST_PATH|- + finch cp [flags] SRC_PATH|- CONTAINER:DEST_PATH +``` + +## Options + +```text + -L, --follow-link Always follow symbolic link in SRC_PATH. + -h, --help help for cp +``` diff --git a/docs/cmd/finch_create.md b/docs/cmd/finch_create.md new file mode 100644 index 000000000..8aabc79f6 --- /dev/null +++ b/docs/cmd/finch_create.md @@ -0,0 +1,95 @@ +# finch create + +Create a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + +```text +finch create [flags] IMAGE [COMMAND] [ARG...] +``` + +## Options + +```text + --add-host strings Add a custom host-to-IP mapping (host:ip) + --blkio-weight uint16 Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + --cap-add strings Add Linux capabilities + --cap-drop strings Drop Linux capabilities + --cgroup-conf strings Configure cgroup v2 (key=value) + --cgroup-parent string Optional parent cgroup for the container + --cgroupns string Cgroup namespace to use, the default depends on the cgroup version ("host"|"private") (default "private") + --cidfile string Write the container ID to the file + --cosign-certificate-identity string The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-identity-regexp string A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer string The OIDC issuer expected in a valid Fulcio certificate for --verify=cosign, e.g. https://token.actions.githubusercontent.com or https://oauth2.sigstore.dev/auth. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer-regexp string A regular expression alternative to --certificate-oidc-issuer for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-key string Path to the public key file, KMS, URI or Kubernetes Secret for --verify=cosign + --cpu-period uint Limit CPU CFS (Completely Fair Scheduler) period + --cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota (default -1) + --cpu-shares uint CPU shares (relative weight) + --cpus float Number of CPUs + --cpuset-cpus string CPUs in which to allow execution (0-3, 0,1) + --cpuset-mems string MEMs in which to allow execution (0-3, 0,1) + --detach-keys string Override the default detach keys (default "ctrl-p,ctrl-q") + --device strings Add a host device to the container + --dns strings Set custom DNS servers + --dns-opt strings Set DNS options + --dns-option strings Set DNS options + --dns-search strings Set custom DNS search domains + --entrypoint stringArray Overwrite the default ENTRYPOINT of the image + -e, --env stringArray Set environment variables + --env-file strings Set environment variables from file + --gpus stringArray GPU devices to add to the container ('all' to pass all GPUs) + --group-add strings Add additional groups to join + --help show help + -h, --hostname string Container host name + --init Run an init process inside the container, Default to use tini + --init-binary string The custom binary to use as the init process (default "tini") + -i, --interactive Keep STDIN open even if not attached + --ip string IPv4 address to assign to the container + --ipc string IPC namespace to use ("host"|"private") + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --isolation string Specify isolation technology for container. On Linux the only valid value is default. Windows options are host, process and hyperv with process isolation as the default (default "default") + --kernel-memory string Kernel memory limit (deprecated) + -l, --label stringArray Set metadata on container + --label-file strings Set metadata on container from file + --log-driver string Logging driver for the container. Default is json-file. It also supports logURI (eg: --log-driver binary://) (default "json-file") + --log-opt stringArray Log driver options + --mac-address string MAC address to assign to the container + -m, --memory string Memory limit + --memory-reservation string Memory soft limit + --memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap + --memory-swappiness int Tune container memory swappiness (0 to 100) (default -1) (default -1) + --mount stringArray Attach a filesystem mount to the container + --name string Assign a name to the container + --net strings Connect a container to a network ("bridge"|"host"|"none"|) (default [bridge]) + --network strings Connect a container to a network ("bridge"|"host"|"none"|"container:"|) (default [bridge]) + --oom-kill-disable Disable OOM Killer + --oom-score-adj int Tune container’s OOM preferences (-1000 to 1000, rootless: 100 to 1000) + --pid string PID namespace to use + --pidfile string file path to write the task's pid + --pids-limit int Tune container pids limit (set -1 for unlimited) (default -1) + --platform string Set platform (e.g. "amd64", "arm64") + --privileged Give extended privileges to this container + -p, --publish strings Publish a container's port(s) to the host + --pull string Pull image before running ("always"|"missing"|"never") (default "missing") + --rdt-class string Name of the RDT class (or CLOS) to associate the container with + --read-only Mount the container's root filesystem as read only + --restart string Restart policy to apply when a container exits (implemented values: "no"|"always|on-failure:n|unless-stopped") (default "no") + --rm Automatically remove the container when it exits + --rootfs The first argument is not an image but the rootfs to the exploded container + --runtime string Runtime to use for this container, e.g. "crun", or "io.containerd.runsc.v1" (default "io.containerd.runc.v2") + --security-opt stringArray Security options + --shm-size string Size of /dev/shm + --stop-signal string Signal to stop a container (default "SIGTERM") + --stop-timeout int Timeout (in seconds) to stop a container + --sysctl stringArray Sysctl options + --tmpfs stringArray Mount a tmpfs directory + -t, --tty Allocate a pseudo-TTY + --ulimit strings Ulimit options + --umask string Set the umask inside the container. Defaults to 0022 + -u, --user string Username or UID (format: [:]) + --uts string UTS namespace to use + --verify string Verify the image (none|cosign|notation) (default "none") + -v, --volume stringArray Bind mount a volume + --volumes-from stringArray Mount volumes from the specified container(s) + -w, --workdir string Working directory inside the container +``` diff --git a/docs/cmd/finch_events.md b/docs/cmd/finch_events.md new file mode 100644 index 000000000..e061afcf3 --- /dev/null +++ b/docs/cmd/finch_events.md @@ -0,0 +1,14 @@ +# finch events + +Get real time events from the server + +```text +finch events [flags] +``` + +## Options + +```text + --format string Format the output using the given Go template, e.g, '{{json .}}' + -h, --help help for events +``` diff --git a/docs/cmd/finch_exec.md b/docs/cmd/finch_exec.md new file mode 100644 index 000000000..d5f3c09b9 --- /dev/null +++ b/docs/cmd/finch_exec.md @@ -0,0 +1,21 @@ +# finch exec + +Run a command in a running container + +```text +finch exec [flags] CONTAINER COMMAND [ARG...] +``` + +## Options + +```text + -d, --detach Detached mode: run command in the background + -e, --env stringArray Set environment variables + --env-file strings Set environment variables from file + -h, --help help for exec + -i, --interactive Keep STDIN open even if not attached + --privileged Give extended privileges to the command + -t, --tty Allocate a pseudo-TTY + -u, --user string Username or UID (format: [:]) + -w, --workdir string Working directory inside the container +``` diff --git a/docs/cmd/finch_help.md b/docs/cmd/finch_help.md new file mode 100644 index 000000000..f70168002 --- /dev/null +++ b/docs/cmd/finch_help.md @@ -0,0 +1,14 @@ +# finch help + +Help provides help for any command in the application. +Simply type finch help [path to command] for full details. + +```text + finch help [command] [flags] +``` + +## Options + +```text + -h, --help help for help +``` diff --git a/docs/cmd/finch_history.md b/docs/cmd/finch_history.md new file mode 100644 index 000000000..a7be4cfb6 --- /dev/null +++ b/docs/cmd/finch_history.md @@ -0,0 +1,16 @@ +# finch history + +Show the history of an image + +```text +finch history [flags] IMAGE +``` + +## Options + +```text + -f, --format string Format the output using the given Go template, e.g, '{{json .}}' + -h, --help help for history + --no-trunc Don't truncate output + -q, --quiet Only show numeric IDs +``` diff --git a/docs/cmd/finch_image.md b/docs/cmd/finch_image.md new file mode 100644 index 000000000..65463aa1f --- /dev/null +++ b/docs/cmd/finch_image.md @@ -0,0 +1,32 @@ +# finch image + +Manage images + +```text +finch image [flags] +``` + +## Commands + +```text + build Build an image from a Dockerfile. Needs buildkitd to be running. + convert convert an image + decrypt decrypt an image + encrypt encrypt image layers + history Show the history of an image + inspect Display detailed information on one or more images. + load Load an image from a tar archive or STDIN + ls List images + prune Remove unused images + pull Pull an image from a registry. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + push Push an image or a repository to a registry. Optionally specify "ipfs://" or "ipns://" scheme to push image to IPFS. + rm Remove one or more images + save Save one or more images to a tar archive (streamed to STDOUT by default) + tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE +``` + +## Options + +```text + -h, --help help for image +``` diff --git a/docs/cmd/finch_images.md b/docs/cmd/finch_images.md new file mode 100644 index 000000000..e8afd62d5 --- /dev/null +++ b/docs/cmd/finch_images.md @@ -0,0 +1,31 @@ +# finch images + +List images + +## Properties + +- REPOSITORY: Repository +- TAG: Tag +- NAME: Name of the image, --names for skip parsing as repository and tag. +- IMAGE ID: OCI Digest. Usually different from Docker image ID. Shared for multi-platform images. +- CREATED: Created time +- PLATFORM: Platform +- SIZE: Size of the unpacked snapshots +- BLOB SIZE: Size of the blobs (such as layer tarballs) in the content store + +```text +finch images [flags] [REPOSITORY[:TAG]] +``` + +## Options + +```text + -a, --all (unimplemented yet, always true) (default true) + --digests Show digests (compatible with Docker, unlike ID) + -f, --filter strings Filter output based on conditions provided + --format string Format the output using the given Go template, e.g, '{{json .}}', 'wide' + -h, --help help for images + --names Show image names + --no-trunc Don't truncate output + -q, --quiet Only show numeric IDs +``` diff --git a/docs/cmd/finch_info.md b/docs/cmd/finch_info.md new file mode 100644 index 000000000..d86ec8cb8 --- /dev/null +++ b/docs/cmd/finch_info.md @@ -0,0 +1,15 @@ +# finch info + +Display system-wide information + +```text +finch info [flags] +``` + +## Options + +```text + -f, --format string Format the output using the given Go template, e.g, '{{json .}}' + -h, --help help for info + --mode string Information mode, "dockercompat" for Docker-compatible output, "native" for containerd-native output (default "dockercompat") +``` diff --git a/docs/cmd/finch_inspect.md b/docs/cmd/finch_inspect.md new file mode 100644 index 000000000..758a4177a --- /dev/null +++ b/docs/cmd/finch_inspect.md @@ -0,0 +1,16 @@ +# finch inspect + +Return low-level information on objects. + +```text +finch inspect [flags] +``` + +## Options + +```text + -f, --format string Format the output using the given Go template, e.g, '{{json .}}' + -h, --help help for inspect + --mode string Inspect mode, "dockercompat" for Docker-compatible output, "native" for containerd-native output (default "dockercompat") + --type string Return JSON for specified type +``` diff --git a/docs/cmd/finch_kill.md b/docs/cmd/finch_kill.md new file mode 100644 index 000000000..536fcc44c --- /dev/null +++ b/docs/cmd/finch_kill.md @@ -0,0 +1,14 @@ +# finch kill + +Kill one or more running containers + +```text +finch kill [flags] CONTAINER [CONTAINER, ...] +``` + +## Options + +```text + -h, --help help for kill + -s, --signal string Signal to send to the container (default "KILL") +``` diff --git a/docs/cmd/finch_load.md b/docs/cmd/finch_load.md new file mode 100644 index 000000000..d60dfc636 --- /dev/null +++ b/docs/cmd/finch_load.md @@ -0,0 +1,16 @@ +# finch load + +Supports both Docker Image Spec v1.2 and OCI Image Spec v1.0. + +```text +finch load [flags] +``` + +## Options + +```text + --all-platforms Import content for all platforms + -h, --help help for load + -i, --input string Read from tar archive file, instead of STDIN + --platform strings Import content for a specific platform +``` diff --git a/docs/cmd/finch_login.md b/docs/cmd/finch_login.md new file mode 100644 index 000000000..d8ca14965 --- /dev/null +++ b/docs/cmd/finch_login.md @@ -0,0 +1,16 @@ +# finch login + +Log in to a container registry + +```text +finch login [flags] [SERVER] +``` + +## Options + +```text + -h, --help help for login + -p, --password string Password + --password-stdin Take the password from stdin + -u, --username string Username +``` diff --git a/docs/cmd/finch_logout.md b/docs/cmd/finch_logout.md new file mode 100644 index 000000000..39346977c --- /dev/null +++ b/docs/cmd/finch_logout.md @@ -0,0 +1,13 @@ +# finch logout + +Log out from a container registry + +```text +finch logout [flags] [SERVER] +``` + +## Options + +```text + -h, --help help for logout +``` diff --git a/docs/cmd/finch_logs.md b/docs/cmd/finch_logs.md new file mode 100644 index 000000000..39efc2773 --- /dev/null +++ b/docs/cmd/finch_logs.md @@ -0,0 +1,23 @@ +# finch logs + +Fetch the logs of a container. + +The following containers are supported: +- Containers created with 'finch run -d'. The log is currently empty for containers created without '-d'. +- Containers created with 'finch compose'. +- Containers created with Kubernetes (EXPERIMENTAL). + +```text +finch logs [flags] CONTAINER +``` + +## Options + +```text + -f, --follow Follow log output + -h, --help help for logs + --since string Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) + -n, --tail string Number of lines to show from the end of the logs (default "all") + -t, --timestamps Show timestamps + --until string Show logs before a timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes) +``` diff --git a/docs/cmd/finch_network.md b/docs/cmd/finch_network.md new file mode 100644 index 000000000..1fb3b0415 --- /dev/null +++ b/docs/cmd/finch_network.md @@ -0,0 +1,23 @@ +# finch network + +Manage networks + +```text +finch network [flags] +``` + +## Commands + +```text + create Create a network + inspect Display detailed information on one or more networks + ls List networks + prune Remove all unused networks + rm Remove one or more networks +``` + +## Options + +```text + -h, --help help for network +``` diff --git a/docs/cmd/finch_pause.md b/docs/cmd/finch_pause.md new file mode 100644 index 000000000..13231d848 --- /dev/null +++ b/docs/cmd/finch_pause.md @@ -0,0 +1,13 @@ +# finch pause + +Pause all processes within one or more containers + +```text +finch pause [flags] CONTAINER [CONTAINER, ...] +``` + +## Options + +```text + -h, --help help for pause +``` diff --git a/docs/cmd/finch_port.md b/docs/cmd/finch_port.md new file mode 100644 index 000000000..94ba2d781 --- /dev/null +++ b/docs/cmd/finch_port.md @@ -0,0 +1,13 @@ +# finch port + +List port mappings or a specific mapping for the container + +```text +finch port [flags] CONTAINER [PRIVATE_PORT[/PROTO]] +``` + +## Options + +```text + -h, --help help for port +``` diff --git a/docs/cmd/finch_ps.md b/docs/cmd/finch_ps.md new file mode 100644 index 000000000..a4dda03dd --- /dev/null +++ b/docs/cmd/finch_ps.md @@ -0,0 +1,21 @@ +# finch ps + +List containers + +```text +finch ps [flags] +``` + +## Options + +```text + -a, --all Show all containers (default shows just running) + -f, --filter strings Filter matches containers based on given conditions + --format string Format the output using the given Go template, e.g, '{{json .}}', 'wide' + -h, --help help for ps + -n, --last int Show n last created containers (includes all states) (default -1) + -l, --latest Show the latest created container (includes all states) + --no-trunc Don't truncate output + -q, --quiet Only display container IDs + -s, --size Display total file sizes +``` diff --git a/docs/cmd/finch_pull.md b/docs/cmd/finch_pull.md new file mode 100644 index 000000000..7c5b0366b --- /dev/null +++ b/docs/cmd/finch_pull.md @@ -0,0 +1,24 @@ +# finch pull + +Pull an image from a registry. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + +```text +finch pull [flags] NAME[:TAG] +``` + +## Options + +```text + --all-platforms Pull content for all platforms + --cosign-certificate-identity string The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-identity-regexp string A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer string The OIDC issuer expected in a valid Fulcio certificate for --verify=cosign,, e.g. https://token.actions.githubusercontent.com or https://oauth2.sigstore.dev/auth. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer-regexp string A regular expression alternative to --certificate-oidc-issuer for --verify=cosign,. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-key string Path to the public key file, KMS, URI or Kubernetes Secret for --verify=cosign + -h, --help help for pull + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --platform strings Pull content for a specific platform + -q, --quiet Suppress verbose output + --unpack string Unpack the image for the current single platform (auto/true/false) (default "auto") + --verify string Verify the image (none|cosign|notation) (default "none") +``` diff --git a/docs/cmd/finch_push.md b/docs/cmd/finch_push.md new file mode 100644 index 000000000..e2ba4a661 --- /dev/null +++ b/docs/cmd/finch_push.md @@ -0,0 +1,25 @@ +# finch push + +Push an image or a repository to a registry. Optionally specify "ipfs://" or "ipns://" scheme to push image to IPFS. + +```text +finch push [flags] NAME[:TAG] +``` + +## Options + +```text + --all-platforms Push content for all platforms + --allow-nondistributable-artifacts Allow pushing images with non-distributable blobs + --cosign-key string Path to the private key file, KMS URI or Kubernetes Secret for --sign=cosign + --estargz Convert the image into eStargz + -h, --help help for push + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --ipfs-ensure-image Ensure the entire contents of the image is locally available before push (default true) + --notation-key-name string Signing key name for a key previously added to notation's key list for --sign=notation + --platform strings Push content for a specific platform + -q, --quiet Suppress verbose output + --sign string Sign the image (none|cosign|notation (default "none") + --soci-min-layer-size int Minimum layer size to build zTOC for. Smaller layers won't have zTOC and not lazy pulled. Default is 10 MiB. (default -1) + --soci-span-size int Span size that soci index uses to segment layer data. Default is 4 MiB. (default -1) +``` diff --git a/docs/cmd/finch_restart.md b/docs/cmd/finch_restart.md new file mode 100644 index 000000000..78881a81a --- /dev/null +++ b/docs/cmd/finch_restart.md @@ -0,0 +1,14 @@ +# finch restart + +Restart one or more running containers + +```text +finch restart [flags] CONTAINER [CONTAINER, ...] +``` + +## Options + +```text + -h, --help help for restart + -t, --time uint Seconds to wait for stop before killing it (default 10) +``` diff --git a/docs/cmd/finch_rm.md b/docs/cmd/finch_rm.md new file mode 100644 index 000000000..a99986707 --- /dev/null +++ b/docs/cmd/finch_rm.md @@ -0,0 +1,15 @@ +# finch rm + +Remove one or more containers + +```text +finch rm [flags] CONTAINER [CONTAINER, ...] +``` + +## Options + +```text + -f, --force Force the removal of a running|paused|unknown container (uses SIGKILL) + -h, --help help for rm + -v, --volumes Remove volumes associated with the container +``` diff --git a/docs/cmd/finch_rmi.md b/docs/cmd/finch_rmi.md new file mode 100644 index 000000000..a9e6bbad0 --- /dev/null +++ b/docs/cmd/finch_rmi.md @@ -0,0 +1,15 @@ +# finch rmi + +Remove one or more images + +```text +finch rmi [flags] IMAGE [IMAGE, ...] +``` + +## Options + +```text + --async Asynchronous mode + -f, --force Force removal of the image + -h, --help help for rmi +``` diff --git a/docs/cmd/finch_run.md b/docs/cmd/finch_run.md new file mode 100644 index 000000000..79f004e8a --- /dev/null +++ b/docs/cmd/finch_run.md @@ -0,0 +1,96 @@ +# finch run + +Run a command in a new container. Optionally specify "ipfs://" or "ipns://" scheme to pull image from IPFS. + +```text +finch run [flags] IMAGE [COMMAND] [ARG...] +``` + +## Options + +```text + --add-host strings Add a custom host-to-IP mapping (host:ip) + --blkio-weight uint16 Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + --cap-add strings Add Linux capabilities + --cap-drop strings Drop Linux capabilities + --cgroup-conf strings Configure cgroup v2 (key=value) + --cgroup-parent string Optional parent cgroup for the container + --cgroupns string Cgroup namespace to use, the default depends on the cgroup version ("host"|"private") (default "private") + --cidfile string Write the container ID to the file + --cosign-certificate-identity string The identity expected in a valid Fulcio certificate for --verify=cosign. Valid values include email address, DNS names, IP addresses, and URIs. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-identity-regexp string A regular expression alternative to --cosign-certificate-identity for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-identity or --cosign-certificate-identity-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer string The OIDC issuer expected in a valid Fulcio certificate for --verify=cosign, e.g. https://token.actions.githubusercontent.com or https://oauth2.sigstore.dev/auth. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-certificate-oidc-issuer-regexp string A regular expression alternative to --certificate-oidc-issuer for --verify=cosign. Accepts the Go regular expression syntax described at https://golang.org/s/re2syntax. Either --cosign-certificate-oidc-issuer or --cosign-certificate-oidc-issuer-regexp must be set for keyless flows + --cosign-key string Path to the public key file, KMS, URI or Kubernetes Secret for --verify=cosign + --cpu-period uint Limit CPU CFS (Completely Fair Scheduler) period + --cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota (default -1) + --cpu-shares uint CPU shares (relative weight) + --cpus float Number of CPUs + --cpuset-cpus string CPUs in which to allow execution (0-3, 0,1) + --cpuset-mems string MEMs in which to allow execution (0-3, 0,1) + -d, --detach Run container in background and print container ID + --detach-keys string Override the default detach keys (default "ctrl-p,ctrl-q") + --device strings Add a host device to the container + --dns strings Set custom DNS servers + --dns-opt strings Set DNS options + --dns-option strings Set DNS options + --dns-search strings Set custom DNS search domains + --entrypoint stringArray Overwrite the default ENTRYPOINT of the image + -e, --env stringArray Set environment variables + --env-file strings Set environment variables from file + --gpus stringArray GPU devices to add to the container ('all' to pass all GPUs) + --group-add strings Add additional groups to join + --help show help + -h, --hostname string Container host name + --init Run an init process inside the container, Default to use tini + --init-binary string The custom binary to use as the init process (default "tini") + -i, --interactive Keep STDIN open even if not attached + --ip string IPv4 address to assign to the container + --ipc string IPC namespace to use ("host"|"private") + --ipfs-address string multiaddr of IPFS API (default uses $IPFS_PATH env variable if defined or local directory ~/.ipfs) + --isolation string Specify isolation technology for container. On Linux the only valid value is default. Windows options are host, process and hyperv with process isolation as the default (default "default") + --kernel-memory string Kernel memory limit (deprecated) + -l, --label stringArray Set metadata on container + --label-file strings Set metadata on container from file + --log-driver string Logging driver for the container. Default is json-file. It also supports logURI (eg: --log-driver binary://) (default "json-file") + --log-opt stringArray Log driver options + --mac-address string MAC address to assign to the container + -m, --memory string Memory limit + --memory-reservation string Memory soft limit + --memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap + --memory-swappiness int Tune container memory swappiness (0 to 100) (default -1) (default -1) + --mount stringArray Attach a filesystem mount to the container + --name string Assign a name to the container + --net strings Connect a container to a network ("bridge"|"host"|"none"|) (default [bridge]) + --network strings Connect a container to a network ("bridge"|"host"|"none"|"container:"|) (default [bridge]) + --oom-kill-disable Disable OOM Killer + --oom-score-adj int Tune container’s OOM preferences (-1000 to 1000, rootless: 100 to 1000) + --pid string PID namespace to use + --pidfile string file path to write the task's pid + --pids-limit int Tune container pids limit (set -1 for unlimited) (default -1) + --platform string Set platform (e.g. "amd64", "arm64") + --privileged Give extended privileges to this container + -p, --publish strings Publish a container's port(s) to the host + --pull string Pull image before running ("always"|"missing"|"never") (default "missing") + --rdt-class string Name of the RDT class (or CLOS) to associate the container with + --read-only Mount the container's root filesystem as read only + --restart string Restart policy to apply when a container exits (implemented values: "no"|"always|on-failure:n|unless-stopped") (default "no") + --rm Automatically remove the container when it exits + --rootfs The first argument is not an image but the rootfs to the exploded container + --runtime string Runtime to use for this container, e.g. "crun", or "io.containerd.runsc.v1" (default "io.containerd.runc.v2") + --security-opt stringArray Security options + --shm-size string Size of /dev/shm + --stop-signal string Signal to stop a container (default "SIGTERM") + --stop-timeout int Timeout (in seconds) to stop a container + --sysctl stringArray Sysctl options + --tmpfs stringArray Mount a tmpfs directory + -t, --tty Allocate a pseudo-TTY + --ulimit strings Ulimit options + --umask string Set the umask inside the container. Defaults to 0022 + -u, --user string Username or UID (format: [:]) + --uts string UTS namespace to use + --verify string Verify the image (none|cosign|notation) (default "none") + -v, --volume stringArray Bind mount a volume + --volumes-from stringArray Mount volumes from the specified container(s) + -w, --workdir string Working directory inside the container +``` diff --git a/docs/cmd/finch_save.md b/docs/cmd/finch_save.md new file mode 100644 index 000000000..15e78e4b4 --- /dev/null +++ b/docs/cmd/finch_save.md @@ -0,0 +1,16 @@ +# finch save + +The archive implements both Docker Image Spec v1.2 and OCI Image Spec v1.0. + +```text +finch save [flags] +``` + +## Options + +```text + --all-platforms Export content for all platforms + -h, --help help for save + -o, --output string Write to a file, instead of STDOUT + --platform strings Export content for a specific platform +``` diff --git a/docs/cmd/finch_start.md b/docs/cmd/finch_start.md new file mode 100644 index 000000000..fa70a3ea2 --- /dev/null +++ b/docs/cmd/finch_start.md @@ -0,0 +1,15 @@ +# finch start + +Start one or more running containers + +```text +finch start [flags] CONTAINER [CONTAINER, ...] +``` + +## Options + +```text + -a, --attach Attach STDOUT/STDERR and forward signals + --detach-keys string Override the default detach keys (default "ctrl-p,ctrl-q") + -h, --help help for start +``` diff --git a/docs/cmd/finch_stats.md b/docs/cmd/finch_stats.md new file mode 100644 index 000000000..93b8c8bfb --- /dev/null +++ b/docs/cmd/finch_stats.md @@ -0,0 +1,17 @@ +# finch stats + +Display a live stream of container(s) resource usage statistics. + +```text +finch stats [flags] +``` + +## Options + +```text + -a, --all Show all containers (default shows just running) + --format string Pretty-print images using a Go template, e.g, '{{json .}}' + -h, --help help for stats + --no-stream Disable streaming stats and only pull the first result + --no-trunc Do not truncate output +``` diff --git a/docs/cmd/finch_stop.md b/docs/cmd/finch_stop.md new file mode 100644 index 000000000..5800177f3 --- /dev/null +++ b/docs/cmd/finch_stop.md @@ -0,0 +1,14 @@ +# finch stop + +Stop one or more running containers + +```text +finch stop [flags] CONTAINER [CONTAINER, ...] +``` + +## Options + +```text + -h, --help help for stop + -t, --time int Seconds to wait before sending a SIGKILL (default 10) +``` diff --git a/docs/cmd/finch_support-bundle_generate.md b/docs/cmd/finch_support-bundle_generate.md new file mode 100644 index 000000000..e2974168f --- /dev/null +++ b/docs/cmd/finch_support-bundle_generate.md @@ -0,0 +1,15 @@ +# finch support-bundle generate + +Generates a collection of logs and configs that can be uploaded to a Github issue to help debug issues. + +```text + finch support-bundle generate [flags] +``` + +## Options + +```text + --exclude stringArray files to exclude from the support bundle. if you specify a base name, all files matching that base name will be excluded. if you specify an absolute or relative path, only exact matches will be excluded + -h, --help help for generate + --include stringArray additional files to include in the support bundle, specified by absolute or relative path. to include a file from the VM, prefix the file path with "vm:" +``` diff --git a/docs/cmd/finch_system.md b/docs/cmd/finch_system.md new file mode 100644 index 000000000..30783bc2b --- /dev/null +++ b/docs/cmd/finch_system.md @@ -0,0 +1,21 @@ +# finch system + +Manage containerd + +```text +finch system [flags] +``` + +## Commands + +```text + events Get real time events from the server + info Display system-wide information + prune Remove unused data +``` + +## Options + +```text + -h, --help help for system +``` diff --git a/docs/cmd/finch_tag.md b/docs/cmd/finch_tag.md new file mode 100644 index 000000000..9afa9abbc --- /dev/null +++ b/docs/cmd/finch_tag.md @@ -0,0 +1,13 @@ +# finch tag + +Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE + +```text +finch tag [flags] SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG] +``` + +## Options + +```text + -h, --help help for tag +``` diff --git a/docs/cmd/finch_top.md b/docs/cmd/finch_top.md new file mode 100644 index 000000000..207800903 --- /dev/null +++ b/docs/cmd/finch_top.md @@ -0,0 +1,13 @@ +# finch top + +Display the running processes of a container + +```text +finch top CONTAINER [ps OPTIONS] [flags] +``` + +## Options + +```text + -h, --help help for top +``` diff --git a/docs/cmd/finch_unpause.md b/docs/cmd/finch_unpause.md new file mode 100644 index 000000000..3ed37619a --- /dev/null +++ b/docs/cmd/finch_unpause.md @@ -0,0 +1,13 @@ +# finch unpause + +Unpause all processes within one or more containers + +```text +finch unpause [flags] CONTAINER [CONTAINER, ...] +``` + +## Options + +```text + -h, --help help for unpause +``` diff --git a/docs/cmd/finch_update.md b/docs/cmd/finch_update.md new file mode 100644 index 000000000..829df1317 --- /dev/null +++ b/docs/cmd/finch_update.md @@ -0,0 +1,26 @@ +# finch update + +Update one or more running containers + +```text +finch update [flags] CONTAINER [CONTAINER, ...] +``` + +## Options + +```text + --blkio-weight uint16 Block IO (relative weight), between 10 and 1000, or 0 to disable (default 0) + --cpu-period uint Limit CPU CFS (Completely Fair Scheduler) period + --cpu-quota int Limit CPU CFS (Completely Fair Scheduler) quota (default -1) + --cpu-shares uint CPU shares (relative weight) + --cpus float Number of CPUs + --cpuset-cpus string CPUs in which to allow execution (0-3, 0,1) + --cpuset-mems string MEMs in which to allow execution (0-3, 0,1) + -h, --help help for update + --kernel-memory string Kernel memory limit (deprecated) + -m, --memory string Memory limit + --memory-reservation string Memory soft limit + --memory-swap string Swap limit equal to memory plus swap: '-1' to enable unlimited swap + --pids-limit int Tune container pids limit (set -1 for unlimited) (default -1) + --restart string Restart policy to apply when a container exits (implemented values: "no"|"always|on-failure:n|unless-stopped") (default "no") +``` diff --git a/docs/cmd/finch_version.md b/docs/cmd/finch_version.md new file mode 100644 index 000000000..9f18cd88f --- /dev/null +++ b/docs/cmd/finch_version.md @@ -0,0 +1,13 @@ +# finch version + +Shows Finch version information + +```text + finch version [flags] +``` + +## Options + +```text + -h, --help help for version +``` diff --git a/docs/cmd/finch_vm_init.md b/docs/cmd/finch_vm_init.md new file mode 100644 index 000000000..00e3e5093 --- /dev/null +++ b/docs/cmd/finch_vm_init.md @@ -0,0 +1,13 @@ +# finch vm init + +Initialize the virtual machine + +```text + finch vm init [flags] +``` + +## Options + +```text + -h, --help help for init +``` diff --git a/docs/cmd/finch_vm_remove.md b/docs/cmd/finch_vm_remove.md new file mode 100644 index 000000000..d027de487 --- /dev/null +++ b/docs/cmd/finch_vm_remove.md @@ -0,0 +1,14 @@ +# finch vm remove + +Remove the virtual machine instance + +```text + finch vm remove [flags] +``` + +## Options + +```text + -f, --force forcibly remove finch VM + -h, --help help for remove +``` diff --git a/docs/cmd/finch_vm_start.md b/docs/cmd/finch_vm_start.md new file mode 100644 index 000000000..720e24ca1 --- /dev/null +++ b/docs/cmd/finch_vm_start.md @@ -0,0 +1,13 @@ +# finch vm start + +Start the virtual machine + +```text + finch vm start [flags] +``` + +## Options + +```text + -h, --help help for start +``` diff --git a/docs/cmd/finch_vm_status.md b/docs/cmd/finch_vm_status.md new file mode 100644 index 000000000..ef43aef59 --- /dev/null +++ b/docs/cmd/finch_vm_status.md @@ -0,0 +1,13 @@ +# finch vm status + +Status of the virtual machine + +```text + finch vm status [flags] +``` + +## Options + +```text + -h, --help help for status +``` diff --git a/docs/cmd/finch_vm_stop.md b/docs/cmd/finch_vm_stop.md new file mode 100644 index 000000000..4ea379834 --- /dev/null +++ b/docs/cmd/finch_vm_stop.md @@ -0,0 +1,14 @@ +# finch vm stop + +Stop the virtual machine + +```text + finch vm stop [flags] +``` + +## Options + +```text + -f, --force forcibly stop finch VM + -h, --help help for stop +``` diff --git a/docs/cmd/finch_volume.md b/docs/cmd/finch_volume.md new file mode 100644 index 000000000..bd79abcc4 --- /dev/null +++ b/docs/cmd/finch_volume.md @@ -0,0 +1,23 @@ +# finch volume + +Manage volumes + +```text +finch volume [flags] +``` + +## Commands + +```text + create Create a volume + inspect Display detailed information on one or more volumes + ls List volumes + prune Remove all unused local volumes + rm Remove one or more volumes +``` + +## Options + +```text + -h, --help help for volume +``` diff --git a/docs/cmd/finch_wait.md b/docs/cmd/finch_wait.md new file mode 100644 index 000000000..fb5af58a8 --- /dev/null +++ b/docs/cmd/finch_wait.md @@ -0,0 +1,13 @@ +# finch wait + +Block until one or more containers stop, then print their exit codes. + +```text +finch wait [flags] CONTAINER [CONTAINER, ...] +``` + +## Options + +```text + -h, --help help for wait +``` diff --git a/pkg/mocks/gen_docs_system_deps.go b/pkg/mocks/gen_docs_system_deps.go new file mode 100644 index 000000000..465e37894 --- /dev/null +++ b/pkg/mocks/gen_docs_system_deps.go @@ -0,0 +1,80 @@ +// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. +// SPDX-License-Identifier: Apache-2.0 + +// Code generated by MockGen. DO NOT EDIT. +// Source: gen_docs.go + +// Package mocks is a generated GoMock package. +package mocks + +import ( + os "os" + reflect "reflect" + + gomock "github.com/golang/mock/gomock" +) + +// GenDocsSystemDeps is a mock of GenDocsSystemDeps interface. +type GenDocsSystemDeps struct { + ctrl *gomock.Controller + recorder *GenDocsSystemDepsMockRecorder +} + +// GenDocsSystemDepsMockRecorder is the mock recorder for GenDocsSystemDeps. +type GenDocsSystemDepsMockRecorder struct { + mock *GenDocsSystemDeps +} + +// NewGenDocsSystemDeps creates a new mock instance. +func NewGenDocsSystemDeps(ctrl *gomock.Controller) *GenDocsSystemDeps { + mock := &GenDocsSystemDeps{ctrl: ctrl} + mock.recorder = &GenDocsSystemDepsMockRecorder{mock} + return mock +} + +// EXPECT returns an object that allows the caller to indicate expected use. +func (m *GenDocsSystemDeps) EXPECT() *GenDocsSystemDepsMockRecorder { + return m.recorder +} + +// Pipe mocks base method. +func (m *GenDocsSystemDeps) Pipe() (*os.File, *os.File, error) { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "Pipe") + ret0, _ := ret[0].(*os.File) + ret1, _ := ret[1].(*os.File) + ret2, _ := ret[2].(error) + return ret0, ret1, ret2 +} + +// Pipe indicates an expected call of Pipe. +func (mr *GenDocsSystemDepsMockRecorder) Pipe() *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Pipe", reflect.TypeOf((*GenDocsSystemDeps)(nil).Pipe)) +} + +// SetStdout mocks base method. +func (m *GenDocsSystemDeps) SetStdout(arg0 *os.File) { + m.ctrl.T.Helper() + m.ctrl.Call(m, "SetStdout", arg0) +} + +// SetStdout indicates an expected call of SetStdout. +func (mr *GenDocsSystemDepsMockRecorder) SetStdout(arg0 interface{}) *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "SetStdout", reflect.TypeOf((*GenDocsSystemDeps)(nil).SetStdout), arg0) +} + +// Stdout mocks base method. +func (m *GenDocsSystemDeps) Stdout() *os.File { + m.ctrl.T.Helper() + ret := m.ctrl.Call(m, "Stdout") + ret0, _ := ret[0].(*os.File) + return ret0 +} + +// Stdout indicates an expected call of Stdout. +func (mr *GenDocsSystemDepsMockRecorder) Stdout() *gomock.Call { + mr.mock.ctrl.T.Helper() + return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Stdout", reflect.TypeOf((*GenDocsSystemDeps)(nil).Stdout)) +} diff --git a/pkg/system/stdlib.go b/pkg/system/stdlib.go index dc2102971..33b29eb64 100644 --- a/pkg/system/stdlib.go +++ b/pkg/system/stdlib.go @@ -42,6 +42,10 @@ func (s *StdLib) LookupEnv(key string) (string, bool) { return os.LookupEnv(key) } +func (s *StdLib) Pipe() (*os.File, *os.File, error) { + return os.Pipe() +} + func (s *StdLib) Stdin() *os.File { return os.Stdin } @@ -50,6 +54,10 @@ func (s *StdLib) Stdout() *os.File { return os.Stdout } +func (s *StdLib) SetStdout(w *os.File) { + os.Stdout = w +} + func (s *StdLib) Stderr() *os.File { return os.Stderr } diff --git a/pkg/system/system.go b/pkg/system/system.go index 9c589b4da..8143f88c8 100644 --- a/pkg/system/system.go +++ b/pkg/system/system.go @@ -52,6 +52,11 @@ type EnvChecker interface { LookupEnv(key string) (string, bool) } +// PipeGetter mocks out os.Pipe. +type PipeGetter interface { + Pipe() (*os.File, *os.File, error) +} + // StdinGetter mocks out os.Stdin. type StdinGetter interface { Stdin() *os.File @@ -62,6 +67,11 @@ type StdoutGetter interface { Stdout() *os.File } +// StdoutSetter mocks out redirecting os.Stdout. +type StdoutSetter interface { + SetStdout(*os.File) +} + // StderrGetter mocks out os.Stderr. type StderrGetter interface { Stderr() *os.File