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.
@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();
})();
const options = {
cwd: process.cwd(),
match: undefined,
includeMergedTags: false,
};
const { lastTagName, lastVersion, refCount, sha, isDirty } = describe.sync(options);
const result = describe.parse("v1.0.0-5-gdeadbeef");
Install lerna for access to the lerna
CLI.
6.0.0 (2022-10-12)
Super fast, modern task-runner implementation for lerna run
As of version 6.0.0, Lerna will now delegate the implementation details of the lerna run
command to the super fast, modern task-runner (powered by Nx) by default.
If for some reason you wish to opt in to the legacy task-runner implementation details (powered by p-map
and p-queue
), you can do so by setting "useNx": false
in your lerna.json. (Please let us know via a Github issue if you feel the need to do that, however, as in general the new task-runner should just work how you expect it to as a lerna user).
Interactive configuration for lerna run
caching and task pipelines via the new lerna add-caching
command
When using the modern task-runner implementation described above, the way to get the most out of it is to tell it about the outputs of your various scripts, and also any relationships that exist between them (such as needing to run the build
script before the test
, for example).
Simply run lerna add-caching
and follow the instructions in order to generate all the relevant configuration for your workspace.
You can learn more about the configuration it generates here: https://lerna.js.org/docs/concepts/task-pipeline-configuration
Automatic loading of .env files in lerna run
with the new task-runner implementation
By default the modern task runner powered by Nx will automatically load .env
files for you. You can set --load-env-files
to false if you want to disable this behavior for any reason.
For more details about what .env
files will be loaded by default please see: https://nx.dev/recipes/environment-variables/define-environment-variables
Obsolete options in lerna run
with the new task-runner implementation
There are certain legacy options for lerna run
which are no longer applicable to the modern task-runner. Please see full details about those flags, and the reason behind their obselence, here:
https://lerna.js.org/docs/lerna6-obsolete-options
New lerna repair
command
When configuration changes over time as new versions of a tool are published it can be tricky to keep up with the changes and sometimes it's possible to miss out on optimizations as a result.
When you run the new command lerna repair
, lerna will execute a series of code migrations/codemods which update your workspace to the latest and greatest best practices for workspace configuration.
The actual codemods which run will be added to over time, but for now one you might see run on your workspace is that it will remove any explicit "useNx": true
references from lerna.json files, because that is no longer necessary and it's cleaner not to have it.
We are really excited about this feature and how we can use it to help users keep their workspaces up to date.