{"id":28566756,"url":"https://github.com/gruntwork-io/go-commons","last_synced_at":"2025-06-10T15:31:07.042Z","repository":{"id":38133499,"uuid":"76992379","full_name":"gruntwork-io/go-commons","owner":"gruntwork-io","description":"A standard library to use in all Gruntwork CLI tools","archived":false,"fork":false,"pushed_at":"2025-04-16T22:58:37.000Z","size":395,"stargazers_count":35,"open_issues_count":10,"forks_count":26,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-06-01T05:56:38.720Z","etag":null,"topics":["cli","cli-apps","golang"],"latest_commit_sha":null,"homepage":"https://www.gruntwork.io/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gruntwork-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-12-20T21:19:13.000Z","updated_at":"2025-01-27T20:03:42.000Z","dependencies_parsed_at":"2022-07-09T13:16:04.025Z","dependency_job_id":"1d2bcef5-9d4f-4251-8fca-7ce372cd944d","html_url":"https://github.com/gruntwork-io/go-commons","commit_stats":{"total_commits":92,"total_committers":16,"mean_commits":5.75,"dds":0.5,"last_synced_commit":"2129e742bab30d27ef715eb32dd71c3f02a41f05"},"previous_names":["gruntwork-io/gruntwork-cli"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgo-commons","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgo-commons/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgo-commons/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgo-commons/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gruntwork-io","download_url":"https://codeload.github.com/gruntwork-io/go-commons/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruntwork-io%2Fgo-commons/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259101104,"owners_count":22805202,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cli-apps","golang"],"created_at":"2025-06-10T15:30:53.253Z","updated_at":"2025-06-10T15:31:07.013Z","avatar_url":"https://github.com/gruntwork-io.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Maintained by Gruntwork.io](https://img.shields.io/badge/maintained%20by-gruntwork.io-%235849a6.svg)](https://gruntwork.io/?ref=repo_go-commons)\n[![Go Report Card](https://goreportcard.com/badge/github.com/gruntwork-io/go-commons)](https://goreportcard.com/report/github.com/gruntwork-io/go-commons)\n[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go\u0026logoColor=white\u0026style=flat-square)](https://pkg.go.dev/mod/github.com/gruntwork-io/go-commons?tab=overview)\n![go.mod version](https://img.shields.io/github/go-mod/go-version/gruntwork-io/go-commons)\n\n# Gruntwork Go Commons\n\nThis repo contains common libraries and helpers used by Gruntwork for building CLI tools in Go.\n\n**NOTE: This repo was renamed from gruntwork-cli starting v0.8.0. Update your gruntwork-cli references to go-commons.**\n\n## Packages\n\nThis repo contains the following packages:\n\n* collections\n* entrypoint\n* errors\n* files\n* logging\n* shell\n* ssh\n* retry\n* awscommons\n* env\n\nEach of these packages is described below.\n\n### collections\n\nThis package contains useful helper methods for working with collections such as lists and maps, as Go has very few of\nthese built-in.\n\n### entrypoint\n\nMost CLI apps built by Gruntwork should use this package to run their app, as it takes\ncare of common tasks such as setting the proper exit code, rendering stack\ntraces, handling panics, and rendering help text in a standard format. Note\nthat this package assumes you are using\n[urfave/cli](https://github.com/urfave/cli), which is currently our library of\nchoice for CLI apps.\n\nHere is the typical usage pattern in `main.go`:\n\n```go\npackage main\n\nimport (\n        \"github.com/urfave/cli/v2\"\n        \"github.com/gruntwork-io/go-commons/entrypoint\"\n        \"github.com/gruntwork-io/go-commons/version\"\n)\n\nfunc main() {\n      // Create a new CLI app. This will return a urfave/cli App with some\n      // common initialization.\n      // Set the version number from your app from the Version variable that is passed in at build time in `version` package\n      // for more understanding see github.com/gruntwork-io/go-commons/version\n      app := entrypoint.NewApp(\"my-app-name\", version.GetVersion())\n\n      app.Authors = []*cli.Author{\n            {\n                Name: \"Gruntwork\",\n                Email: \"www.gruntwork.io\",\n            },\n      }\n\n      app.Action = func(cliContext *cli.Context) error {\n        // ( fill in your app details)\n        return nil\n      }\n\n      // Run your app using the entrypoint package, which will take care of exit codes, stack traces, and panics\n      entrypoint.RunApp(app)\n}\n```\n\n### errors\n\nIn our CLI apps, we should try to ensure that:\n\n1. Every error has a stacktrace. This makes debugging easier.\n1. Every error generated by our own code (as opposed to errors from Go built-in functions or errors from 3rd party\n   libraries) has a custom type. This makes error handling more precise, as we can decide to handle different types of\n   errors differently.\n\nTo accomplish these two goals, we have created an `errors` package that has several helper methods, such as\n`errors.WithStackTrace(err error)`, which wraps the given `error` in an Error object that contains a stacktrace. Under\nthe hood, the `errors` package is using the [go-errors](https://github.com/go-errors/errors) library, but this may\nchange in the future, so the rest of the code should not depend on `go-errors` directly.\n\nHere is how the `errors` package should be used:\n\n1. Any time you want to create your own error, create a custom type for it, and when instantiating that type, wrap it\n   with a call to `errors.WithStackTrace`. That way, any time you call a method defined in our own code, you know the\n   error it returns already has a stacktrace and you don't have to wrap it yourself.\n1. Any time you get back an error object from a function built into Go or a 3rd party library, immediately wrap it with\n   `errors.WithStackTrace`. This gives us a stacktrace as close to the source as possible.\n1. If you need to get back the underlying error, you can use the `errors.IsError` and `errors.Unwrap` functions.\n1. If you want to return an error that forces a specific exit code, wrap it with `errors.ErrorWithExitCode`.\n\nNote that `entrypoint.RunApp` takes care of showing stack traces and handling exit codes.\n\n### files\n\nThis package has a number of helpers for working with files and file paths, including one-liners for checking if a\ngiven path is a file or a directory, reading a file as a string, and building relative and canonical file paths.\n\n### logging\n\nThis package contains utilities for logging from our CLI apps. Instead of using Go's built-in logging library, we are\nusing [logrus](github.com/sirupsen/logrus), as it supports log levels (INFO, WARN, DEBUG, etc), structured logging\n(making key=value pairs easier to parse), log formatting (including text and JSON), hooks to connect logging to a\nvariety of external systems (e.g. syslog, airbrake, papertrail), and even hooks for automated testing.\n\nTo get a Logger, call the `logging.GetLogger` method:\n\n```go\nlogger := logging.GetLogger(\"my-app\", \"v0.0.1\")\nlogger.Info(\"Something happened!\")\n```\n\nTo change the logging level globally, call the `SetGlobalLogLevel` function:\n\n```go\nlogging.SetGlobalLogLevel(logrus.DebugLevel)\n```\n\nNote that this ONLY affects loggers created using the `GetLogger` function **AFTER** you call `SetGlobalLogLevel`, so\nyou need to call this as early in the life of your CLI app as possible!\n\nTo change the logging format globally, call the `SetGlobalLogFormatter` function:\n\n```go\n//Valid options are \"json\" or \"text\"\nlogging.SetGlobalLogFormatter(\"json\")\n```\n\n### shell\n\nThis package contains two types of helpers:\n\n* `cmd.go`: This file contains helpers for running shell commands.\n* `prompt.go`: This file contains helpers for prompting the user for input (e.g. yes/no).\n\n### ssh\n\nThis package contains helper methods for initiating SSH connections and running commands over the connection.\n\n### retry\n\nThis package contains helper methods for retrying an action up to a limit.\n\n### awscommons\n\nThis package contains routines for interacting with AWS. Meant to provide high level interfaces used throughout various Gruntwork CLIs.\n\nNote that the routines in this package are adapted for `aws-sdk-go-v2`, not v1 (`aws-sdk-go`).\n\n### env\n\nThis package contains helper methods for convenient work with environment variables.\n\n## Running tests\n\n```\ngo test -v ./...\n```\n\n## License\n\nThis code is released under the MIT License. See [LICENSE.txt](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgruntwork-io%2Fgo-commons","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgruntwork-io%2Fgo-commons","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgruntwork-io%2Fgo-commons/lists"}