@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

5.0.0 (2022-05-24)

Lerna workspaces no longer have dependency deprecation warnings.

Bug Fixes

• replace read-package-tree with @npmcli/arborist (#3133) (f1c10a4)
• resolve most dependency audit issues (#3127) (2b3b191)

BREAKING CHANGES

• Node v10.x and v12.x are no longer supported.

  • Please upgrade to the latest LTS release of Node (we recommend either v14 or v16).

• Internally npm lifecycle scripts are now invoked using @npmcli/run-script instead of npm-lifecycle in order to modernize the package and fix package vulnerabilities and deprecations.

  • We are classing this as a breaking change because the APIs of npm-lifecycle and @npmcli/run-script are significantly different, despite @npmcli/run-script being the official successor to npm-lifecycle.

    We have successfully made the integration test suite we inherited pass with this change, but there may potentially be aspects related to it which are not covered by the tests and are breaking. If you encounter any issues you believe are related to this change please open a new issue with a dedicated reproduction for us to look into!