= gum :linkattrs: :project-owner: kordamp :project-name: gm

image:https://github.com/{project-owner}/{project-name}/workflows/Build/badge.svg["Build Status", link="https://github.com/{project-owner}/{project-name}/actions"] image:https://goreportcard.com/badge/github.com/{project-owner}/{project-name}["GoReport Card", link="https://goreportcard.com/report/github.com/{project-owner}/{project-name}"] image:https://img.shields.io/codecov/c/github/{project-owner}/{project-name}/master.svg["Coveralls", link="https://codecov.io/gh/{project-owner}/{project-name}"] image:https://img.shields.io/github/v/release/{project-owner}/{project-name}["Release", link="https://github.com/{project-owner}/{project-name}/releases"] image:https://snapcraft.io/gum/badge.svg["Snapcraft", link="https://snapcraft.io/gum"] image:https://img.shields.io/github/downloads/{project-owner}/{project-name}/total?color=blue&logo=github["Downloads, link="https://github.com/{project-owner}/{project-name}/releases"]

---

Gum is a link:https://gradle.org[Gradle]/link:https:maven.apache.org[Maven]/link:https://github.com/sormuras/bach/[Bach]/link:https://github.com/jbangdev[JBang]/link:https://ant.apache.org/[Ant] wrapper written in link:https://golang.org/[Go], inspired in link:https://github.com/dougborg/gdub[https://github.com/dougborg/gdub] and link:https://github.com/srs/gw[https://github.com/srs/gw].

Gum automatically detects if the project is Gradle, Maven, Bach, JBang or Ant based and runs the appropriate command. However in the case that Gum guesses wrong you canforce a specific build tool to be used. Similarly as gdub, Gum lets you invoke either Gradle, Maven, or Ant from anywhere within the project structure, not just the root directory.

== Usage

Gum supports the following flags

• -ga force Ant execution
• -gb force Bach execution
• -gc displays current configuration and quits
• -gd displays debug information
• -gg force Gradle build
• -gh displays help information
• -gj force JBang execution
• -gm force Maven build
• -gn executes nearest build file
• -gq run gm in quiet mode
• -gr do not replace goals/tasks
• -gv displays version information

Gum will execute the build based on the root build file unless -gn is specified, in which case the nearest build file will be selected. If a specific build file is given (-b, --build-file for Gradle; -f, --file for Maven, -f, -file, -buildfile for Ant) then that file will be used instead.

Gum works by passing the given arguments to the resolved tool; it will replace common goal/task names following these mappings

|=== | Maven | Gradle | compile | classes | package | assemble | verify | build | verify | check | install | publishToMavenLocal | exec:java | run | dependency:tree | dependencies |===

The following tasks are mapped from Gradle to Maven only

|=== | Gradle | Maven | jar | package | check | verify |===

You can skip these replacements by defining the -gr flag.

Gum can be used to run Maven and Gradle builds like so:

.Maven [source]

$ gm build

Which results in the invocation of either mvnw or mvn with the verify goal as build gets replaced by verify.

.Gradle [source]

$ gm verify

Which results in the invocation of either gradlew or gradle with the build goal as verify gets replaced with build.

.jbang

Gum will execute a given file (local or remote) if explicitly defined, otherwise scans the the current directory and executes the first file with .java,.jsh, .jar that's found (in that order) unless a different order were to be configured.

== Configuration

You may configure some aspects of Gum using a link:https://github.com/toml-lang/toml[TOML] based configuration file. There are two possible locations for this file

• At the project's root directory. Must be named .gm.toml.
• At your home directory. For Linux/MacOS it's $HOME/.gm.toml, for Windows it's %APPDATA\Gum\gm.toml.

Settings at the project root override those at your home directory. The format is

[source,toml] .gm.toml

[theme]

valid values are [none, dark, light, custom]

name = "dark"

if name = custom then you must define the following 5 entries

color values follow https://github.com/gookit/color#use-a-256-color-style

color values must be between 0 and 255

first value is foreground

second value is background

symbol = [125, 0] section = [47, 0] key = [130, 0] boolean = [200, 0] literal = [23, 0]

[general]

same as passing -gq

quiet = false

same as passing -gd

debug = false

tool discovery order

default order is the following

discovery = ["gradle", "maven", "ant", "bach", "jbang"]

[gradle]

if goal/tasks should be replaced, same as passing -gr

replace = true

if the default replace mappings should be used

defaults = true

maven -> gradle mappings

[gradle.mappings] compile = "classes" "exec:java" = "run"

[maven]

if goal/tasks should be replaced, same as passing -gr

replace = true

if the default replace mappings should be used

defaults = true

gives priority to mvnd over mvnw/mvn

mvnd = false

gradle -> mappings

[maven.mappings] build = "verify"

[jbang]

source file discovery order

default order is the following

discovery = [".java", ".jsh", ".jar"]

[bach]

Bach version to use

version = "16.0.2"

== Installation

=== Homebrew

Use the kordamp/homebrew-tap

[source]

$ brew install kordamp/tap/gum

Or use the upgrade or reinstall commands if you have a previous installation of Gum in your system.

== Scoop

[source]

$ scoop install main/gum

=== Manually

Download the pre-compiled binaries from the link:https://github.com/kordamp/gm/releases[releases page] and copy to the desired location.

=== Installing from Source

You need Go installed on your system, follow link:https://golang.org/dl/[this link] to download and install. Once Go is installed you can invoke the following command to install Gum

[source,go]

go install github.com/kordamp/gm

Executables are installed in the directory named by the GOBIN environment variable, which defaults to $GOPATH/bin or $HOME/go/bin if the GOPATH environment variable is not set. Make sure that $HOME/go/bin is in your $PATH. If GOPATH is defined then $GOPATH/bin must be in your $PATH.

=== Compiling from Source

You need Go installed on your system, follow link:https://golang.org/dl/[this link] to download and install. Once Go is installed you can invoke the following command to install Gum

.Clone: [source]

$ git clone https://github.com/kordamp/gm $ cd gm

.Build: [source]

$ make

.Verify: [source]

$ ./gm -gv

.Test [source]

$ go test -v ./...

== FAQ

=== Oh My ZSH incompatibility

If you try to execute gm you might get error messages like these:

• not a git repository
• not something we can merge

This happens, if you have link:https://ohmyz.sh/[oh-my-zsh] installed on your system. The git plugin registers the alias gm for git merge. That overrides the gm command from Gum. To solve this problem, remove the git plugin from the list of plugins to load in your ~/.zshrc file.

==== Example

.Before [source,properties]

plugins=(docker git sdk)

.After [source,properties]

plugins=(docker sdk)