gbld is a hot-reloader and build-automation utility for Go projects. It automatically tracks build numbers, formats source files using goimports, compiles the binary, manages the running process, and watches the project directory for changes to trigger automatic rebuilding and restarting.

Key Features

🔄 Hot Reloader: Automatically watches for file changes (via fsnotify) and rebuilds/restarts your application instantly.
🔢 Build Counter: Increments a build number in build.go automatically with every compiled build.
🧹 Auto-Import & Formatting: Runs goimports on save (optional via -i) to keep your imports and formatting clean.
🖥️ Interactive Menu: Uses a select menu (gbld.menu.json) if run without arguments, letting you define and run custom build tasks.
🚀 Cross-Compilation: Easily builds binaries for multiple target operating systems (macOS, Linux, Windows) and architectures (amd64, arm64) using a single command.
☁️ Remote Uploads: Integrated command to securely upload build artifacts to a deployment server (gozilla).

Installation

Prerequisites

Make sure you have Go and goimports installed and available in your system path:

go install golang.org/x/tools/cmd/goimports@latest

Building from Source

Clone the repository and compile gbld:

git clone https://git.fhi.mpg.de/mike/gbld.git
cd gbld
go build -o /usr/local/bin/gbld

Usage

gbld [flags] [target_name]

Note

If target_name is omitted, the name of the current directory is used. The tool expects a main source file matching that name (e.g., target_name.go).

CLI Flags

Flag	Argument	Description
`-b`	None	Build-only mode (compiles the binary but does not run it).
`-1`	None	Run once (does not watch the directory for changes).
`-i`	None	Runs `goimports` to clean up imports before building.
`-o`	`<args>`	Space-separated arguments to pass to the compiled binary on execution.
`-c`	`<command>`	Command to execute immediately after a successful build (before execution).
`-a`	None	Builds binaries for all supported platforms (Windows, macOS, Linux for AMD64/ARM64).
`-u`	None	Uploads built binaries via SSH/SCP to the `gozilla` server.
`-v`	None	Displays the current version of `gbld`.
`-h`	None	Displays help and usage information.

Configuration (`gbld.menu.json`)

To make running common tasks easier, you can place a gbld.menu.json file in your project directory. If you run gbld without any flags, it will parse this file and present an interactive selection menu:

{
  "Build and Run (hot reload)": ["-i"],
  "Build Only": ["-b", "-i", "-1"],
  "Show Help": ["-h"]
}

Under the Hood

Build Increment

When compiling, gbld parses build.go to find a pattern matching var build = "<number>". It increments this number by 1 and updates the file automatically. This is useful for stamping build numbers/versions inside your binary.

Automatic Backups

Before gbld runs goimports on a file or modifies build.go, it creates a timestamped backup in a ./tmp/ directory inside the project workspace:

./tmp/gbld.go.20260625145800

Process Management

When hot-reloading, gbld handles process termination gracefully:

It sends an os.Interrupt (SIGINT) to the running binary.
It waits up to 1 second for the process to exit clean.
If it does not exit within the timeout, it terminates the process forcefully (SIGKILL).

README.md

gbld — Simple Go Builder & Live-Reloader