esbuild-plugin-git-describe

An esbuild plugin to expose git-describe as a module in your application.

This plugin was inspired by esbuild-plugin-version-injector.

Description

This plugin allows you to expose versioning information based on the results of git-describe at build time as a module that can be imported into front-end code.

For example:

import { hash, tag, raw } from 'git-describe';

console.log("App Version: ", { hash, tag, raw });

/* Will be something like:
 * {
 *   hash: "g8b914ab",
 *   raw: "v0.1.0-0-g8b914ab-dirty",
 *   tag: "v0.1.0"
 * }
 */

This git-describe object is generated by the plugin at compile time so there is no version management needed beyond git tags. See the git-describe example output for the list of available properties.

Installation

This plugin is available on npm as esbuild-plugin-git-describe and can be installed using npm with:

npm install --save-dev esbuild-plugin-git-describe

Usage

Add the plugin to your esbuild script. For example:

import * as esbuild from 'esbuild';
import { esbuildPluginGitDescribe } from 'esbuild-plugin-git-describe';

await esbuild.build({
  entryPoints: [resolve(__dirname, './src/index.ts'],
  plugins: [ esbuildPluginGitDescribe() ]
});

Configuration Options:

You can pass a configuration object to esbuildPluginGetDescribe() which accepts the following values:

Property Name	Property Type	Description
dirtyMark	string	From git-describe, the dirty mark to use if repo state is dirty (see git describe's --dirty). Defaults to '-dirty'.
dirtySemver	boolean	From git-describe, appends the dirty mark to semverString if repo state is dirty. Defaults to true.
long	boolean	From git-describe, always adds commit distance and hash to raw, suffix and .toString() (matches the behaviour of git describe's --long). Defaults to true.
longSemver	boolean	From git-describe, always adds commit distance and hash to semverString (similar to git describe's --long, but for semver). Defaults to false.
requireAnnotated	boolean	From git-describe, uses --tags if false, so that simple git tags are allowed. Defaults to false.
match	string	From git-describe, uses --match to filter tag names. By default only tags resembling a version number are considered. Defaults to 'v[0-9]*'.
customArguments	Array<string>	From git-describe, array of additional arguments to pass to git describe. Not all arguments are useful and some may even break the library, but things like --abbrev and --candidates should be safe to add. Defaults to [].
namespace	string	Namespace to use as the source of the git-describe variables exposed to the application. Defaults to git-describe.