gm

= 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.

=== Snapcraft

[source]
----
$ sudo snap install --classic gum
----

== 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)
----