README
¶
magetools
General tooling helpers for simplifying cross repository automation using Mage.
The test coverage shown is informal, as these aren't setup always with full standard tests. Primarily the tests just import and run to confirm no errors. When possible, I do test the functionality.
Mage is a good case of a little magic making things faster and easier to adopt, while making it a bit trickier to test functions IMO.
Other Go Focused Tools for Task Automation
Worth an honorable mention is Goyek which has a similar goal to Mage, but approaches with less magic and a similar design to writing tests. I opted not to use after a few months of working with it due to the alpha level changes occuring in project, and more effort required on adding tasks and remote imports[remote-imports-with-goyek].
If you don't have any desire to use remote imports, then Goyek can be a good option if you want to write in a style like Go testing.
Lastly, another worthy mention is Gosh.
Remote Packages
Mage
Install with Go 1.16+
go install github.com/magefile/mage@latest
Mage-Select
Nice little interactive prompt.
Alias: mage-select as mages
go install github.com/iwittkau/mage-select@latest
Getting Started With Mage
I need a way to bootstrap projects quickly with some tasks, so these directories give two different templates.
simple-single-file: The simpliest for small projects, contains all tasks in single file.root-imports-with-tasks-in-subdirectory: Organized for normal projects, this provides a zero-install run (usinggo run mage.go taskname) and also organizes tasks into subdirectory. This allows the root of the project to remain clean. Tasks can then be easily split into files in the tasks directory such as:mage.git.go, mage.js.go, etc.
Why [dot] prefix in directory?
Go commands that run like go test ./... automatically ignore dot or underscore prefixed files.
I prefer to the dot prefix and underscore isn't very common from what I've observed in the Go echo system.
Tip
Include mage_output_file.go in your gitignore file to avoid it causing consternation in your git diff monitoring tooling.
Examples
The examples directory contains random mage examples I've used that don't fit yet into a package, or I haven't had the need to add any tests to reuse this in multiple places.
How To Use
// mage:import
_ "github.com/sheldonhull/magetools/ci"
Namespaced
// mage:import ci
"github.com/sheldonhull/magetools/ci"
Update
Quickly refresh library by running this on caller. This should bypass the cached public version and call directly to quickly update if the cached go pkg version isn't registering an update.
GOPRIVATE=github.com/sheldonhull/* go get -u
GOPRIVATE=github.com/sheldonhull/* go get -u github.com/sheldonhull/magetools/gotools@latest
$ENV:GOPRIVATE='github.com/sheldonhull/*'
Allow Zero Install Run
From the Mage Docs, see mage.go.
Run this using: go run main.go and it should work just like using mage directly.
Future
Possibly best to setup with a dedicated templating tool in the future (something like Cookiecutter) but for now this is just an easy copy and paste in VSCode.
Directories
¶
| Path | Synopsis |
|---|---|
|
ci helps identify when a task is running in a ci context and not interactively Currently this supports checking: 1.
|
ci helps identify when a task is running in a ci context and not interactively Currently this supports checking: 1. |
|
Docker package provides common docker commands.
|
Docker package provides common docker commands. |
|
fancy uses pterm to provide some nice output that's not really critical but makes the experience nicer with summary
|
fancy uses pterm to provide some nice output that's not really critical but makes the experience nicer with summary |
|
Package gittools provides automatic setup of some useful git tooling like Bit and Git Town
|
Package gittools provides automatic setup of some useful git tooling like Bit and Git Town |
|
Provide Go linting, formatting and other basic tooling.
|
Provide Go linting, formatting and other basic tooling. |
|
pkg
|
|
|
magetoolsutils
loghelper provides simple helper functions for enabling or disabling more logging with Pterm.
|
loghelper provides simple helper functions for enabling or disabling more logging with Pterm. |
|
req
Package req provides methods to resolve Go oriented tooling paths, and if not found attempts to install on demand.
|
Package req provides methods to resolve Go oriented tooling paths, and if not found attempts to install on demand. |
|
retool tooling helps bootstrap a project with locally vendored executables and tools.
|
retool tooling helps bootstrap a project with locally vendored executables and tools. |
|
Secrets package runs gitleaks
|
Secrets package runs gitleaks |
|
starter
|
|
|
root-imports-with-tasks-in-subdirectory/magefiles/tasks
⚡ Core Mage Tasks
|
⚡ Core Mage Tasks |
|
Package tooling provides common tooling install setup for go linting, formatting, and other Go tools with nice console output for interactive use.
|
Package tooling provides common tooling install setup for go linting, formatting, and other Go tools with nice console output for interactive use. |