package module
Version: v1.0.3 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2018 License: MIT Imports: 16 Imported by: 1



Used to build and restart a Go project when it crashes or some watched file changes
Aimed to be used in development only.

Software License Linux - Build Status Windows - Build status Coverage Status Go Doc Go Report Card


go get -u


See Releases for detailed history changes.


   gaper - Used to build and restart a Go project when it crashes or some watched file changes

   gaper [global options] command [command options] [arguments...]


     help, h  Shows a list of commands or help for one command

   --bin-name value                 name for the binary built by gaper for the executed program (default current directory name)
   --build-path value               path to the program source code (default: ".")
   --build-args value               arguments used on building the program
   --program-args value             arguments used on executing the program
   --verbose                        turns on the verbose messages from gaper
   --disable-default-ignore         turns off default ignore for hidden files and folders, "*_test.go" files, and vendor folder
   --watch value, -w value          list of folders or files to watch for changes
   --ignore value, -i value         list of folders or files to ignore for changes
   --poll-interval value, -p value  how often in milliseconds to poll watched files for changes (default: 500)
   --extensions value, -e value     a comma-delimited list of file extensions to watch for changes (default: "go")
   --no-restart-on value, -n value  don't automatically restart the supervised program if it ends:
                                      if "error", an exit code of 0 will still restart.
                                      if "exit", no restart regardless of exit code.
                                      if "success", no restart only if exit code is 0.
   --help, -h                       show help
   --version, -v                    print the version

Since in most projects there is no need to watch changes of:

  • hidden files and folders
  • test files (*_test.go)
  • vendor folder

Gaper by default ignores those cases already. Although, if you need Gaper to watch those files anyway it is possible to disable this setting with --disable-default-ignore argument.


Using all defaults provided by Gaper:


Ignore watch over all test files:

no need for this in case if you are not using --disable-default-ignore

--ignore './**/*_test.go'


See the Contributing guide for steps on how to contribute to this project.


This package was heavily inspired by gin and node-supervisor.

Basically, Gaper is a mixing of those projects above. It started from gin code base and I rewrote it aiming to get something similar to node-supervisor (but simpler). A big thanks for those projects and for the people behind it! 👏👏

How is Gaper different of Gin

The main difference is that Gaper removes a layer of complexity from Gin which has a proxy running on top of the executed server. It allows to postpone a build and reload the server when the first call hits it. With Gaper we don't care about that feature, it just restarts your server whenever a change is made.



Package gaper implements a supervisor restarts a go project when it crashes or a watched file changes



View Source
const OSWindows = "windows"

OSWindows is used to check if current OS is a Windows


View Source
var (
	NoRestartOnError   = "error"
	NoRestartOnSuccess = "success"
	NoRestartOnExit    = "exit"

No restart types

View Source
var DefaultBuildPath = "."

DefaultBuildPath is the default build and watched path

View Source
var DefaultExtensions = []string{"go"}

DefaultExtensions is the default watched extension

View Source
var DefaultPoolInterval = 500

DefaultPoolInterval is the time in ms used by the watcher to wait between scans


func Run

func Run(cfg *Config, chOSSiginal chan os.Signal) error

Run starts the whole gaper process watching for file changes or exit codes and restarting the program


type Builder

type Builder interface {
	Build() error
	Binary() string

Builder is a interface for the build process

func NewBuilder

func NewBuilder(dir string, bin string, wd string, buildArgs []string) Builder

NewBuilder creates a new builder

type Config

type Config struct {
	BinName              string
	BuildPath            string
	BuildArgs            []string
	BuildArgsMerged      string
	ProgramArgs          []string
	ProgramArgsMerged    string
	WatchItems           []string
	IgnoreItems          []string
	PollInterval         int
	Extensions           []string
	NoRestartOn          string
	DisableDefaultIgnore bool
	WorkingDirectory     string

Config contains all settings supported by gaper

type LoggerEntity added in v1.0.2

type LoggerEntity struct {
	// contains filtered or unexported fields

LoggerEntity used by gaper

func Logger

func Logger() *LoggerEntity

Logger give access to external packages to use gaper logger

func (*LoggerEntity) Debug added in v1.0.2

func (l *LoggerEntity) Debug(v ...interface{})

Debug logs a debug message

func (*LoggerEntity) Debugf added in v1.0.2

func (l *LoggerEntity) Debugf(format string, v ...interface{})

Debugf logs a debug message with format

func (*LoggerEntity) Error added in v1.0.2

func (l *LoggerEntity) Error(v ...interface{})

Error logs an error message

func (*LoggerEntity) Errorf added in v1.0.2

func (l *LoggerEntity) Errorf(format string, v ...interface{})

Errorf logs and error message with format

func (*LoggerEntity) Info added in v1.0.2

func (l *LoggerEntity) Info(v ...interface{})

Info logs a info message

func (*LoggerEntity) Verbose added in v1.0.2

func (l *LoggerEntity) Verbose(verbose bool)

Verbose toggle this logger verbosity

type Runner

type Runner interface {
	Run() (*exec.Cmd, error)
	Kill() error
	Errors() chan error
	Exited() bool
	IsRunning() bool
	ExitStatus(err error) int

Runner is a interface for the run process

func NewRunner

func NewRunner(wStdout io.Writer, wStderr io.Writer, bin string, args []string) Runner

NewRunner creates a new runner

type Watcher

type Watcher interface {
	Errors() chan error
	Events() chan string

Watcher is a interface for the watch process

func NewWatcher

func NewWatcher(cfg WatcherConfig) (Watcher, error)

NewWatcher creates a new watcher

type WatcherConfig added in v1.0.1

type WatcherConfig struct {
	DefaultIgnore bool
	PollInterval  int
	WatchItems    []string
	IgnoreItems   []string
	Extensions    []string

WatcherConfig defines the settings available for the watcher


Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL