https://github.com/gruntwork-io/go-commons
A standard library to use in all Gruntwork CLI tools
https://github.com/gruntwork-io/go-commons
cli cli-apps golang
Last synced: 8 months ago
JSON representation
A standard library to use in all Gruntwork CLI tools
- Host: GitHub
- URL: https://github.com/gruntwork-io/go-commons
- Owner: gruntwork-io
- License: mit
- Created: 2016-12-20T21:19:13.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2025-04-16T22:58:37.000Z (10 months ago)
- Last Synced: 2025-06-01T05:56:38.720Z (9 months ago)
- Topics: cli, cli-apps, golang
- Language: Go
- Homepage: https://www.gruntwork.io/
- Size: 386 KB
- Stars: 35
- Watchers: 19
- Forks: 26
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
[](https://gruntwork.io/?ref=repo_go-commons)
[](https://goreportcard.com/report/github.com/gruntwork-io/go-commons)
[](https://pkg.go.dev/mod/github.com/gruntwork-io/go-commons?tab=overview)
# Gruntwork Go Commons
This repo contains common libraries and helpers used by Gruntwork for building CLI tools in Go.
**NOTE: This repo was renamed from gruntwork-cli starting v0.8.0. Update your gruntwork-cli references to go-commons.**
## Packages
This repo contains the following packages:
* collections
* entrypoint
* errors
* files
* logging
* shell
* ssh
* retry
* awscommons
* env
Each of these packages is described below.
### collections
This package contains useful helper methods for working with collections such as lists and maps, as Go has very few of
these built-in.
### entrypoint
Most CLI apps built by Gruntwork should use this package to run their app, as it takes
care of common tasks such as setting the proper exit code, rendering stack
traces, handling panics, and rendering help text in a standard format. Note
that this package assumes you are using
[urfave/cli](https://github.com/urfave/cli), which is currently our library of
choice for CLI apps.
Here is the typical usage pattern in `main.go`:
```go
package main
import (
"github.com/urfave/cli/v2"
"github.com/gruntwork-io/go-commons/entrypoint"
"github.com/gruntwork-io/go-commons/version"
)
func main() {
// Create a new CLI app. This will return a urfave/cli App with some
// common initialization.
// Set the version number from your app from the Version variable that is passed in at build time in `version` package
// for more understanding see github.com/gruntwork-io/go-commons/version
app := entrypoint.NewApp("my-app-name", version.GetVersion())
app.Authors = []*cli.Author{
{
Name: "Gruntwork",
Email: "www.gruntwork.io",
},
}
app.Action = func(cliContext *cli.Context) error {
// ( fill in your app details)
return nil
}
// Run your app using the entrypoint package, which will take care of exit codes, stack traces, and panics
entrypoint.RunApp(app)
}
```
### errors
In our CLI apps, we should try to ensure that:
1. Every error has a stacktrace. This makes debugging easier.
1. Every error generated by our own code (as opposed to errors from Go built-in functions or errors from 3rd party
libraries) has a custom type. This makes error handling more precise, as we can decide to handle different types of
errors differently.
To accomplish these two goals, we have created an `errors` package that has several helper methods, such as
`errors.WithStackTrace(err error)`, which wraps the given `error` in an Error object that contains a stacktrace. Under
the hood, the `errors` package is using the [go-errors](https://github.com/go-errors/errors) library, but this may
change in the future, so the rest of the code should not depend on `go-errors` directly.
Here is how the `errors` package should be used:
1. Any time you want to create your own error, create a custom type for it, and when instantiating that type, wrap it
with a call to `errors.WithStackTrace`. That way, any time you call a method defined in our own code, you know the
error it returns already has a stacktrace and you don't have to wrap it yourself.
1. Any time you get back an error object from a function built into Go or a 3rd party library, immediately wrap it with
`errors.WithStackTrace`. This gives us a stacktrace as close to the source as possible.
1. If you need to get back the underlying error, you can use the `errors.IsError` and `errors.Unwrap` functions.
1. If you want to return an error that forces a specific exit code, wrap it with `errors.ErrorWithExitCode`.
Note that `entrypoint.RunApp` takes care of showing stack traces and handling exit codes.
### files
This package has a number of helpers for working with files and file paths, including one-liners for checking if a
given path is a file or a directory, reading a file as a string, and building relative and canonical file paths.
### logging
This package contains utilities for logging from our CLI apps. Instead of using Go's built-in logging library, we are
using [logrus](github.com/sirupsen/logrus), as it supports log levels (INFO, WARN, DEBUG, etc), structured logging
(making key=value pairs easier to parse), log formatting (including text and JSON), hooks to connect logging to a
variety of external systems (e.g. syslog, airbrake, papertrail), and even hooks for automated testing.
To get a Logger, call the `logging.GetLogger` method:
```go
logger := logging.GetLogger("my-app", "v0.0.1")
logger.Info("Something happened!")
```
To change the logging level globally, call the `SetGlobalLogLevel` function:
```go
logging.SetGlobalLogLevel(logrus.DebugLevel)
```
Note that this ONLY affects loggers created using the `GetLogger` function **AFTER** you call `SetGlobalLogLevel`, so
you need to call this as early in the life of your CLI app as possible!
To change the logging format globally, call the `SetGlobalLogFormatter` function:
```go
//Valid options are "json" or "text"
logging.SetGlobalLogFormatter("json")
```
### shell
This package contains two types of helpers:
* `cmd.go`: This file contains helpers for running shell commands.
* `prompt.go`: This file contains helpers for prompting the user for input (e.g. yes/no).
### ssh
This package contains helper methods for initiating SSH connections and running commands over the connection.
### retry
This package contains helper methods for retrying an action up to a limit.
### awscommons
This package contains routines for interacting with AWS. Meant to provide high level interfaces used throughout various Gruntwork CLIs.
Note that the routines in this package are adapted for `aws-sdk-go-v2`, not v1 (`aws-sdk-go`).
### env
This package contains helper methods for convenient work with environment variables.
## Running tests
```
go test -v ./...
```
## License
This code is released under the MIT License. See [LICENSE.txt](LICENSE.txt).