jreleaser.github.io/docs/modules/configuration/pages/packagers/jbang.adoc

= JBang

Unleash the power of Java with link:https://github.com/jbangdev/jbang[jbang]. You can publish distributions as JBang
catalogs.

Each separate executable will have its own JBang script. All executables will be collected in the same catalog. Existing
catalogs located at the target repository will be merged into a single catalog.

Snapshots are supported, in which case executables will bear the `-snapshot` suffix in their alias.

include::partial$legend.adoc[]

[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
# icon:dot-circle[]
packagers:
  # icon:dot-circle[]
  jbang:
    # Enables or disables JBang.
    # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    # Defaults to `NEVER`.
    # icon:dot-circle[]
    active: ALWAYS

    # Directory with file templates used to prepare the JBang distribution.
    # Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
    # If specified, path must exist.
    # icon:dot-circle[]
    templateDirectory: path/to/jbang/templates

    # Additional properties used when evaluating templates.
    # icon:dot-circle[] icon:file-alt[]
    extraProperties:
      # Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.
      foo: bar

    # The jbang executable alias.
    # If left undefined, will use `${distribution.executable}`
    # icon:dot-circle[]
    alias: cli

    # Git author used to commit to the catalog repository.
    # icon:dot-circle[]
    commitAuthor:
      # Name used when authoring commits.
      # If left undefined, will use the releaser's commit name.
      # icon:dot-circle[]
      name: jreleaserbot

      # E-mail used when authoring commits.
      # If left undefined, will use the releaser's commit email.
      # icon:dot-circle[]
      email: pass:[jreleaser@kordamp.org]

    # Git repository to push the formula to.
    # Defaults are shown.
    # icon:dot-circle[]
    catalog:

      # The owner of the catalog repository.
      # Defaults to the same owner as the release repository.
      # icon:dot-circle[]
      owner: duke

      # The name of the catalog repository.
      # Defaults to `jbang-catalog`.
      # icon:dot-circle[]
      name: jbang-catalog

      # Username used for authoring commits. Must have write access to the catalog repository.
      # Defaults to the same username as the release repository.
      # icon:dot-circle[]
      username: duke

      # Password or OAuth token with write access to the catalog repository.
      # If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
      # environment variable must be defined.
      # icon:dot-circle[] icon:eye-slash[]
      token: __DO_NOT_SET_HERE__
----
TOML::
+
[source,toml]
[subs="+macros"]
----
# icon:dot-circle[]
[packagers.jbang]

  # Enables or disables JBang.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `NEVER`.
  # icon:dot-circle[]
  active = "ALWAYS"

  # Directory with file templates used to prepare the Jbang distribution.
  # Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
  # If specified, path must exist.
  # icon:dot-circle[]
  templateDirectory = "path/to/jbang/templates"

  # Additional properties used when evaluating templates.
  # icon:dot-circle[] icon:file-alt[]
  extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.

  # The jbang executable alias.
  # If left undefined, will use `${distribution.executable}`
  # icon:dot-circle[]
  alias = "cli"

  # Git author used to commit to the catalog repository.
  # Name used when authoring commits.
  # If left undefined, will use the releaser's commit name.
  # icon:dot-circle[]
  commitAuthor.name = "jreleaserbot"

  # E-mail used when authoring commits.
  # If left undefined, will use the releaser's commit email.
  # icon:dot-circle[]
  commitAuthor.email = "pass:[jreleaser@kordamp.org]"

  # Git repository to push the formula to.
  # Defaults are shown

  # The owner of the catalog repository.
  # Defaults to the same owner as the release repository.
  # icon:dot-circle[]
  catalog.owner = "duke"

  # The name of the catalog repository.
  # Defaults to `jbang-catalog`.
  # icon:dot-circle[]
  catalog.name = "jbang-catalog"

  # Username used for authoring commits. Must have write access to the catalog repository.
  # Defaults to the same username as the release repository.
  # icon:dot-circle[]
  catalog.username = "duke"

  # Password or OAuth token with write access to the catalog repository.
  # If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
  # environment variable must be defined.
  # icon:dot-circle[] icon:eye-slash[]
  catalog.token = "__DO_NOT_SET_HERE__"
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
  // icon:dot-circle[]
  "packagers": {
    // icon:dot-circle[]
    "jbang": {
      // Enables or disables JBang.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // icon:dot-circle[]
      "active": "ALWAYS",

      // Directory with file templates used to prepare the Jbang distribution.
      // Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
      // If specified, path must exist.
      // icon:dot-circle[]
      "templateDirectory": "path/to/jbang/templates",

      // Additional properties used when evaluating templates.
      // icon:dot-circle[] icon:file-alt[]
      "extraProperties": {
        // Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.
        "foo": "bar"
      },

      // The jbang executable alias.
      // If left undefined, will use `${distribution.executable}`
      // icon:dot-circle[]
      "alias": "cli",

      // Git author used to commit to the catalog repository.
      // icon:dot-circle[]
      "commitAuthor": {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // icon:dot-circle[]
        "name": "jreleaserbot",

        // E-mail used when authoring commits.
        // Defaults to `pass:[jreleaser@kordamp.org]`.
        // icon:dot-circle[]
        "email": "pass:[jreleaser@kordamp.org]"
      },

      // Git repository to push the formula to.
      // Defaults are shown.
      // icon:dot-circle[]
      "catalog": {

        // The owner of the catalog repository.
        // Defaults to the same owner as the release repository.
        // icon:dot-circle[]
        "owner": "duke",

        // The name of the catalog repository.
        // Defaults to `jbang-catalog`.
        // icon:dot-circle[]
        "name": "jbang-catalog",

        // Username used for authoring commits. Must have write access to the catalog repository.
        // Defaults to the same username as the release repository.
        // icon:dot-circle[]
        "username": "duke",

        // Password or OAuth token with write access to the catalog repository.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
        // environment variable must be defined.
        // icon:dot-circle[] icon:eye-slash[]
        "token": "__DO_NOT_SET_HERE__"
      }
    }
  }
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<jreleaser>
  <!--
    icon:dot-circle[]
  -->
  <packagers>
    <!--
      icon:dot-circle[]
    -->
    <jbang>
      <!--
        Enables or disables JBang.
        Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `NEVER`.
        icon:dot-circle[]
      -->
      <active>ALWAYS</active>

      <!--
        Directory with file templates used to prepare the Jbang distribution.
        Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
        If specified, path must exist.
        icon:dot-circle[]
      -->
      <templateDirectory>>path/to/jbang/templates</templateDirectory>

      <!--
        Additional properties used when evaluating templates.
        icon:dot-circle[] icon:file-alt[]
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.
        -->
        <foo>bar</foo>
      </extraProperties>

      <!--
        The jbang executable alias.
        If left undefined, will use `${distribution.executable}`
        icon:dot-circle[]
      -->
      <alias>cli</alias>

      <!--
        Git author used to commit to the repository.
        icon:dot-circle[]
      -->
      <commitAuthor>

        <!--
           Name used when authoring commits.
          Defaults to `jreleaserbot`.
          icon:dot-circle[]
        -->
        <name>jreleaserbot</name>

        <!--
          E-mail used when authoring commits.
          Defaults to `pass:[jreleaser@kordamp.org]`.
          icon:dot-circle[]
        -->
        <email>pass:[jreleaser@kordamp.org]</email>
      </commitAuthor>

      <!--
        Git repository to push the formula to.
        Defaults are shown.
        icon:dot-circle[]
      -->
      <catalog>

        <!--
          The owner of the catalog repository.
          Defaults to the same owner as the release repository.
          icon:dot-circle[]
        -->
        <owner>duke</owner>

        <!--
          The name of the catalog repository.
          Defaults to `jbang-catalog`.
          icon:dot-circle[]
        -->
        <name>jbang-catalog</name>

        <!--
          Username used for authoring commits. Must have write access to the catalog repository.
          Defaults to the same username as the release repository.
          icon:dot-circle[]
        -->
        <username>duke</username>

        <!--
          Password or OAuth token with write access to the catalog repository.
          If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
          environment variable must be defined.
          icon:dot-circle[] icon:eye-slash[]
        -->
        <token>__DO_NOT_SET_HERE__</token>
      </catalog>
    </jbang>
  </packagers>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
jreleaser {
  // icon:dot-circle[]
  packagers {
    // icon:dot-circle[]
    jbang {
      // Enables or disables JBang.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // icon:dot-circle[]
      active = 'ALWAYS'

      // Directory with file templates used to prepare the Jbang distribution.
      // Defaults to `src/jreleaser/distributions/${distribution.name}/jbang`.
      // If specified, path must exist.
      // icon:dot-circle[]
      templateDirectory = 'path/to/jbang/templates'

      // Additional properties used when evaluating templates.
      // Key will be capitalized and prefixed with `jbang`, i.e, `jbangFoo`.
      // icon:dot-circle[] icon:file-alt[]
      extraProperties.put('foo', 'bar')

      // The jbang executable alias.
      // If left undefined, will use `${distribution.executable}`
      // icon:dot-circle[]
      alias = 'cli'

      // Git author used to commit to the catalog repository.
      // icon:dot-circle[]
      commitAuthor {
        // Name used when authoring commits.
        // If left undefined, will use the releaser's commit name.
        // icon:dot-circle[]
        name = 'jreleaserbot'

        // E-mail used when authoring commits.
        // If left undefined, will use the releaser's commit email.
        // icon:dot-circle[]
        email = 'pass:[jreleaser@kordamp.org]'
      }

      // Git repository to push the formula to.
      // Defaults are shown.
      // icon:dot-circle[]
      catalog {

        // The owner of the catalog repository.
        // Defaults to the same owner as the release repository.
        // icon:dot-circle[]
        owner = 'duke'

        // The name of the catalog repository.
        // Defaults to `jbang-catalog`.
        // icon:dot-circle[]
        name = 'jbang-catalog'

        // Username used for authoring commits. Must have write access to the catalog repository.
        // Defaults to the same username as the release repository.
        // icon:dot-circle[]
        username = 'duke'

        // Password or OAuth token with write access to the catalog repository.
        // If left unspecified, the `JRELEASER_JBANG_${GIT}_TOKEN`
        // environment variable must be defined.
        // icon:dot-circle[] icon:eye-slash[]
        token = '__DO_NOT_SET_HERE__'
      }
    }
  }
}
----
====

Template files may be initialized using the `template` command.

NOTE: The catalog token environment variable must match with the chosen xref:release/index.adoc[] service, that is, it must
be one of [`JRELEASER_JBANG_GITHUB_TOKEN`, `JRELEASER_JBANG_GITLAB_TOKEN`, `JRELEASER_JBANG_GITEA_TOKEN`].

NOTE: You must define a value for `java.mainClass` in the owning distribution.

NOTE: When the project's version is snapshot, unless manually updated, the default prepared template assumes JARs may be
resolved from link:https://jitpack.io[].

IMPORTANT: Aliases must be unique!

The following property names have additional meaning

[%header, cols="<2,<5", width="100%"]
|===
| Key             | Description
| reverseRepoHost | reversed Git host, i.e. "com.github"
| reverseDomain   | reversed custom link:https://jitpack.io/docs/#custom-domain-name[domain name]
|===

Assuming that the current version is `1.2.3`, and a distribution named `app`, the above configuration will generate
a `app.java` file in the `duke/jbang-catalog` repository:

[source,json]
.jbang-catalog.json
----
{
  "aliases": {
    "app": {
      "script-ref": "app.java",
      "description": "Sample app"
    }
  }
}
----

[source,java]
.app.java
----
//usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 8
//DEPS com.acme:app:1.2.3

public class app {
    public static void main(String... args) throws Exception {
        com.acme.Main.main(args);
    }
}
----

When the version is snapshot then the catalog and the script template change to:

[source,json]
.jbang-catalog.json
----
{
  "aliases": {
    "app-snapshot": {
      "script-ref": "app_snapshot.java",
      "description": "Sample app"
    }
  }
}
----

[source,java]
.app_snapshot.java
----
//usr/bin/env jbang "$0" "$@" ; exit $?
//JAVA 8
//REPOS jitpack
//DEPS com.github.duke:app:main-SNAPSHOT

public class app_snapshot {
    public static void main(String... args) throws Exception {
        com.acme.Main.main(args);
    }
}
----