Stave

A make-like build tool using Go. Write plain Go functions, and Stave will automatically use them as runnable targets.

Stave was forked from mage (originally created by Nate Finch), and adds various features and improvements.

Documentation for stave is available here.

 

(screenshot: output of stave -l in the goctx project)

 

Installation

Using Homebrew

brew tap yaklabco/tap
brew install stave

Using go install

go install github.com/yaklabco/stave@latest

Building & installing from source

git clone https://github.com/yaklabco/stave.git
cd stave
go run bootstrap.go

Using stave in your CI

The most portable, cross-platform way to make stave available in your CI workflow is probably to install it via the Go-based install method:

    steps:
      # ... prev. steps clipped ...
      - name: Install stave
        run: go install github.com/yaklabco/stave@latest

You will, of course, need to install Go in one of the previous steps - for example, by using the setup-go GitHub action.

Quick Start

Create a stavefile.go in your project:

//go:build stave

package main

import "fmt"

// Build compiles the project
func Build() error {
    fmt.Println("Building...")
    return nil
}

// Test runs the test suite
func Test() {
    fmt.Println("Testing...")
}

Then run:

stave build    # Run the Build target
stave test     # Run the Test target
stave -l       # List all targets
stave -h              # Show help
stave -h build # Show help for Build target
stave -v <target>     # Verbose mode
stave -t 5m <target>  # Set timeout

Documentation

Full documentation is available in the docs/ folder.

Differences from mage

Stave was forked from mage, with the following goals (checked items are already implemented as of the latest release of stave).

For more details on any of these features, please see the stave documentation.

• Modernized Go patterns (Go 1.24+)
• Additional shell helpers (sh.Piper, sh.PiperWith)
• Watch-mode, to re-run one or more build targets when watched files change
• Dry-run support (print the command lines that would be executed, but don't run them)
• Modernized CLI, using the wonderful tools developed by the folks at https://github.com/charmbracelet, including pretty-printed -l/--list output
• Command-line completion of targets (via stave completion <shell_name>, or by simply installing stave via Homebrew)
• Automatic detection of circular dependencies in build targets
• Support for native git-hooks management: no more need to use husky or other hooks-management tools; stave will manage your hooks for you, and you can specify stavefile targets directly as hooks
• Integration with direnv: delegate environment variable management to direnv directly from stave using the --direnv flag
• Namespace-level Default targets: run a default target within a namespace by passing only the namespace name (e.g., stave build instead of stave build:default)
• Public functions, exported under pkg/changelog, for automatically generating next version & next build-tag based on Conventional Commits, using svu (included in stave as a module dependency; no need to install separately)
• Public functions, also exported under pkg/changelog, for automatically enforcing keep-a-changelog-compliant CHANGELOG formatting; for enforcing that every push includes an update to the CHANGELOG; and for automatically linkifying your CHANGELOG headings to point to corresponding tag diffs (each can be used / not used separately from one another)

Attribution

This project is a fork of mage, originally created by Nate Finch. Licensed under the Apache License 2.0.

License

Apache License 2.0 - see LICENSE for details.