Galus - Live Reloading for Go Applications

English | Bahasa Indonesia

Galus is a live reloading tool for Go applications, similar to Air or CompileDaemon. It monitors file changes in your project, automatically recompiles, and restarts the application.

Features

• Live Reloading: Automatically detects changes in specified file types (e.g., .go) and recompiles and restarts the application.

• Configurable via .galus.toml: Customize watched directories, file extensions, build commands, and runtime arguments using a TOML configuration file.

• Colorful CLI Output: Provides clear, color-coded output for better user experience (e.g., green for success, red for errors).

• Log Levels: Supports debug, info, warn, error, and off log levels to control output verbosity.

• Rich CLI Commands: Supports init to create a default configuration file, version to display the app version, and help for command usage details.

• Graceful Shutdown: Captures SIGINT/SIGTERM for safe shutdown, with improved Windows support via taskkill. The grace period is configurable via kill_grace.

• Resilient Reloads: A failed build never kills the currently running binary — the last working version keeps serving until a build succeeds.

• Debounced File Events: Bursts of file changes (e.g. saving many files at once) are combined into a single rebuild via a configurable debounce window, instead of rebuilding once per event.

• Full File Event Coverage: Responds to file create, write, remove, and rename events, not just writes.

• Hooks (pre_cmd / post_cmd): Run commands before building (e.g. go vet, go generate) and after the app restarts. A failing pre_cmd aborts the rebuild and keeps the current process running.

• Environment Variables: Inject env vars into both the build command and the running process via the env config option.

• Polling Fallback: When polling = true, Galus periodically scans the project for changes instead of relying solely on filesystem events — useful for editors or Docker bind-mounts that don't emit fsnotify events reliably.

• File Filtering (exclude_file): Exclude files by glob pattern (e.g., ["*_test.go", "*.gen.go"]).

• Dynamic Directory Watching: Automatically watches new directories created after rebuilds.

• Log to File: Optional log_file config to write logs to a file in addition to stdout.

• Configuration Validation: Ensures build_cmd and command_args are valid before starting the live reload process.

• Cross-Platform: Works on any platform supported by Go, with improved Windows support.

Installation

1. Install galus using go get:

   go get github.com/aliftech/galus

2. Install the binary to make galus available globally:

   go install github.com/aliftech/galus

3. Ensure $GOPATH/bin is in your $PATH:

   export PATH=$PATH:$(go env GOPATH)/bin

Usage

1. Initialize a configuration file: In your project directory, run:

   galus init

   This creates a .galus.toml configuration file with default settings.

2. Start live reloading: In your project directory, run:

   galus

   Galus will monitor file changes (e.g., .go files), recompile, and restart your application.

3. Check version:

   galus version

4. Dry run (validate config):

   galus --dry-run

5. Use custom config file:

   galus --config path/to/config.toml

6. Set log level:

   galus --log-level debug

7. Disable colors:

   galus --no-color

8. Show help:

   galus help

Configuration

The .galus.toml file allows you to customize Galus behavior. Example configuration:

root_dir = "."
tmp_dir = "tmp"
include_ext = ["go"]
exclude_dir = [".git", "vendor", "tmp"]
exclude_file = ["*_test.go"]
build_cmd = "go build -o ./tmp/main ."
command_args = ["tmp/main"]
kill_grace = "5s"
debounce = "300ms"
pre_cmd = []
post_cmd = []
env = {}
polling = false
polling_interval = "500ms"
log_file = ""

• root_dir: Directory to monitor for changes.
• tmp_dir: Temporary directory for compiled binaries.
• include_ext: File extensions to monitor (e.g., ["go", "html"]).
• exclude_dir: Directories to ignore.
• exclude_file: File patterns to ignore (supports globs, e.g., ["*_test.go"]).
• build_cmd: Command to compile the application.
• command_args: Arguments to run the binary.
• kill_grace: How long to wait for the running process to stop gracefully (via SIGTERM) before force-killing it.
• debounce: How long to wait after the last file change before rebuilding, combining bursts of events into a single rebuild.
• pre_cmd: Commands to run before each build (e.g. ["go vet ./...", "go generate ./..."]). If any fails, the rebuild is aborted and the current process keeps running.
• post_cmd: Commands to run after the app restarts (e.g. ["go run ./cmd/gen"]). Failures are logged but do not stop the app.
• env: Environment variables applied to both the build and the running process (e.g. { PORT = "8080", DEBUG = "true" }).
• polling: Set to true to scan the project periodically instead of relying solely on filesystem events.
• polling_interval: How often to scan for changes when polling is enabled.
• log_file: Path to a file to write logs to (leave empty for stdout only).

Build with Custom Version

go build -ldflags "-X main.version=1.2.3" -o galus .

Running Tests

go test ./src/domain/... -v

Docker

Galus can be run via Docker, similar to how Air works.

Build the Image

docker build -t galus .

Run with Your Go Project

Mount your Go project as a volume and run Galus inside the container:

docker run -v $(pwd):/app -w /app galus

Galus will watch for file changes and automatically rebuild your application inside the container.

Using Custom Config

Mount your own .galus.toml config file:

docker run -v $(pwd):/app -v $(pwd)/.galus.toml:/app/.galus.toml -w /app galus

Using Docker Compose

Create a docker-compose.yml in your project:

services:
  app:
    image: galus
    volumes:
      - .:/app
    ports:
      - "8080:8080"
    environment:
      - PORT=8080

Then run:

docker compose up

Notes

• The Docker image defaults to polling mode (polling = true) because fsnotify does not work reliably with Docker bind mounts.
• You can override this by mounting your own .galus.toml with polling = false if using Docker Desktop with appropriate filesystem.
• Pass environment variables via -e flag or env config in .galus.toml.

Star History