@lerna/describe-ref

What is @lerna/describe-ref?

@lerna/describe-ref is a utility package that helps in describing the current Git reference in a Lerna-managed monorepo. It provides information about the current Git branch, tag, or commit, which can be useful for versioning and release management in monorepos.

What are @lerna/describe-ref's main functionalities?

Describe the current Git reference

This feature allows you to get a description of the current Git reference, including branch name, tag, or commit hash. The `describeRef` function returns an object with details about the current Git state.

const { describeRef } = require('@lerna/describe-ref');

async function getGitRef() {
  const ref = await describeRef();
  console.log(ref);
}

getGitRef();

Custom base ref

This feature allows you to specify a custom base reference to compare against. The `describeRef` function can take an options object where you can set the `baseRef` to a specific branch or tag.

const { describeRef } = require('@lerna/describe-ref');

async function getCustomBaseRef(baseRef) {
  const ref = await describeRef({ baseRef });
  console.log(ref);
}

getCustomBaseRef('main');

Include distance from base ref

This feature includes the distance (number of commits) from the base reference in the description. The `includeDistance` option can be set to `true` to get this additional information.

const { describeRef } = require('@lerna/describe-ref');

async function getRefWithDistance() {
  const ref = await describeRef({ includeDistance: true });
  console.log(ref);
}

getRefWithDistance();

Other packages similar to @lerna/describe-ref

git-rev-sync

git-rev-sync is a package that provides synchronous access to Git information such as the current branch, commit hash, and tag. It is similar to @lerna/describe-ref but operates synchronously and is not specifically designed for monorepos.

git-describe

git-describe is a package that provides a way to describe a Git commit using tags and commit distance. It is similar to @lerna/describe-ref but focuses on general Git repositories rather than Lerna-managed monorepos.

simple-git

simple-git is a lightweight interface for running Git commands in any Node.js application. It provides a broader range of Git functionalities compared to @lerna/describe-ref, which is more specialized for describing Git references in monorepos.

README

@lerna/describe-ref

Parse git describe output for lerna-related tags

Usage

const { describe } = require("@lerna/describe-ref");

(async () => {
  const { lastTagName, lastVersion, refCount, sha, isDirty } = await describe();
})();

// values listed here are their defaults
const options = {
  cwd: process.cwd(),
  // pass a glob to match tag name, e.g. "v*.*.*"
  match: undefined,
  // if true, omit --first-parent option
  includeMergedTags: false,
};

const { lastTagName, lastVersion, refCount, sha, isDirty } = describe.sync(options);

const result = describe.parse("v1.0.0-5-gdeadbeef");
// { lastTagName, lastVersion, refCount, sha, isDirty }

Install lerna for access to the lerna CLI.

Changelog

6.4.1 (2023-01-12)

Bug Fixes

• run: resolve erroneous failures (#3495) (24d0d5c)