@lerna/version(翻译)

4,034 阅读10分钟

@lerna/version

自上次发布以来包的Bump版本已更改

使用

lerna version 1.0.1 # 明确的
lerna version patch # semver 关键字
lerna version       # 从提示中选择

运行时,此命令执行以下操作:

  • 标识自上一个标记版本以来已更新的包。

  • 提示输入新版本。

  • 修改包元数据以反映新版本,在根目录和每个包中运行适当的生命周期脚本。

  • 提交这些更改并标记提交。

  • 推到git远程。

Positionals

semver bump

lerna version [major | minor | patch | premajor | preminor | prepatch | prerelease]
# 使用下一个语义版本值,这将跳过“为…”选择新版本的提示

当传递此位置参数时,lerna version将跳过版本选择提示并按该关键字递增版本。您仍然必须使用--yes标志来避免所有提示。

预发布

如果您有任何具有预发布版本号的包(例如2.0.0-beta.3),并且您运行带有和非预发布bump(major、minor或patch)的lerna version,它将发布那些先前预发布的包以及自上一个版本以来更改的包。

对于使用常规提交的项目,请使用以下标志进行预发布管理:

  • --conventional-prerelease: 将当前更改发布为预发布版本。
  • --conventional-graduate: 将预发布版本包升级为稳定版本。 运行 lerna version --conventional-commits没有上述标志的常规提交将只在版本已处于prerelease时将当前更改作为prerelease发布。

选项

--allow-branch

与启用了lerna version的git分支相匹配的globs的白名单。在lerna.json中进行配置是最简单的(也是推荐的),但也可以作为CLI选项传递。

{
  "command": {
    "version": {
      "allowBranch": "master"
    }
  }
}

使用上面的配置,当从master节点以外的任何分支运行lerna version时,将失败。将lerna version仅限于master分支被认为是一种最佳实践。

{
  "command": {
    "version": {
      "allowBranch": ["master", "feature/*"]
    }
  }
}

在前面的配置中,任何前缀为feature/的分支都允许使用lerna version。请注意,当分支合并到主分支时,在功能分支中生成git标记充满了潜在的错误。如果标记与它们的原始上下文“分离”(可能通过压缩合并或冲突合并提交),那么以后的lerna version执行将很难确定正确的“自上次发布以来的差异”

总是可以在命令行上重写这个“持久”配置。请谨慎使用。

lerna version --allow-branch hotfix/oops-fix-the-thing

--amend

lerna version --amend
# commit message is retained, and `git push` is skipped.

保留提交消息,并跳过“git push”。

使用此标志运行时,lerna version将对当前提交执行所有更改,而不是添加新的更改。这在持续集成(CI)期间非常有用,可以减少项目历史记录中的提交数量。

为了防止意外的重写,此命令将跳过git push(即,它意味着--no push)。

--changelog-preset

lerna version --conventional-commits --changelog-preset angular-bitbucket

默认情况下,“变更日志”预设设置为“angular”。在某些情况下,您可能需要更改使用其他预设或自定义预设。

预设是常规变更日志的内置或可安装配置的名称。预设可以作为软件包的全名或自动扩展后缀(例如,angular扩展自conventional-changelog-angular)。

--conventional-commits

lerna version --conventional-commits

当使用此标志运行时,lerna version将使用传统的提交规范来确定版本转换和生成变更CHANGELOG.md 文件。

传递--no-changelog将禁用生成(或更新)CHANGELOG.md文件。

--conventional-graduate

lerna version --conventional-commits --conventional-graduate=package-2,package-4

# 强制所有预发布包分级
lerna version --conventional-commits --conventional-graduate

使用此标志运行时,lerna version将使用*对指定的包(逗号分隔)或所有包进行分级。无论当前头是否已释放,此命令都可以工作,类似于--force publish,只是忽略了任何非预发布的包。如果对未指定的包(如果指定包)或不在预发行版中的包进行了更改,则这些包将按通常使用的常规提交进行版本控制。

“Graduating”一个包意味着碰到了预发布版本的非预发布版本,例如。package-1@1.0.0-alpha.0 => package-1@1.0.0.

将不指定包的从属项,但将不指定包的分级。

--conventional-prerelease

lerna version --conventional-commits --conventional-prerelease=package-2,package-4

# 强制预发布所有更改的包
lerna version --conventional-commits --conventional-prerelease

使用此标志运行时,lerna version将使用预发布版本发布指定的包(逗号分隔)或使用*的所有包。将所有未发布的更改作为pre(patch/minor/major/release),方法是在常规提交的版本建议前面加上pre,例如,如果当前的更改包含功能提交,则建议的bump将是minor,因此此标志将导致preminor版本。如果对未指定的包(如果指定包)或已在预发布版中的包进行了更改,则这些包将按通常使用的常规提交进行版本控制。

--create-release

lerna version --conventional-commits --create-release github
lerna version --conventional-commits --create-release gitlab

使用此标志运行时,lerna version将基于更改的包创建正式的GitHub或GitLab版本。需要--conventional-commits,以便生成变更日志。

要使用GitHub进行身份验证,可以定义以下环境变量。

  • GH_TOKEN (required) - 您的GitHub身份验证令牌(在“设置”>“开发人员设置”>“个人访问令牌”下)。
  • GHE_API_URL -使用GitHub Enterprise时,API的绝对URL。
  • GHE_VERSION -使用GitHub Enterprise时,当前安装的GHE版本。支持以下版本

要使用GitLab进行身份验证,可以定义以下环境变量。

  • GL_TOKEN (required) - 您的GitLab身份验证令牌(在“用户设置”>“访问令牌”下)。
  • GL_API_URL - API的绝对URL,包括版本。(默认值:gitlab.com/api/v4)

注意:使用此选项时,不能传递--no changelog。

也可以在中指定此选项lerna.json配置:

{
  "changelogPreset": "angular"
}

如果预置导出一个构建器函数(例如,conventional-changelog-conventionalcommits),您也可以指定预置配置:

{
  "changelogPreset": {
    "name": "conventionalcommits",
    "issueUrlFormat": "{{host}}/{{owner}}/{{repository}}/issues/{{id}}"
  }
}

--exact

lerna version --exact

当使用此标志运行时,lerna version将在更新的包中精确地指定更新的依赖项(没有标点符号),而不是semver兼容(带一个^)。

有关详细信息,请参见package.json依赖关系文档。

--force-publish

lerna version --force-publish=package-2,package-4

# 强制对所有包进行版本控制
lerna version --force-publish

使用此标志运行时,lerna版本将强制发布指定的包(逗号分隔)或使用*发布所有包。

这将跳过对已更改包的lerna changed检查,并强制更新没有git diff更改的包。

--git-remote

lerna version --git-remote upstream

使用此标志运行时,lerna version将把git更改推送到指定的远程而不是源。

--ignore-changes

检测更改的包时忽略与glob匹配的文件中的更改。

lerna version --ignore-changes '**/*.md' '**/__tests__/**'

此选项最好指定为root lerna .json配置,以避免过早对globs进行shell评估,并与lerna diff和lerna changed共享配置:

{
  "ignoreChanges": ["**/__fixtures__/**", "**/__tests__/**", "**/*.md"]
}

传递 --no-ignore-changes以禁用任何现有的持久性配置。

在以下情况下,无论此选项如何,都将始终发布包: 1、该包的最新版本是预发布版本(即1.0.0-alpha、1.0.0-0.3.7等)。 2、包的一个或多个链接依赖项已更改。

--ignore-scripts

当传递此标志时,此标志将禁止在lerna version期间运行生命周期脚本。

--include-merged-tags

lerna version --include-merged-tags

在检测更改的包时包括来自合并分支的标记。

--message

此选项别名为-m以与git commit进行奇偶校验。

lerna version -m "chore(release): publish %s"
# commit message = "chore(release): publish v1.0.0"

lerna version -m "chore(release): publish %v"
# commit message = "chore(release): publish 1.0.0"

# 独立地对包进行版本控制时,不会替换占位符
lerna version -m "chore(release): publish"
# commit message = "chore(release): publish
#
# - package-1@3.0.1
# - package-2@1.5.4"

使用此标志运行时,lerna version在提交发布的版本更新时将使用提供的消息。对于将lerna集成到希望提交消息遵循某些准则的项目中非常有用,例如使用commitizen和/或语义发布的项目。

如果信息包含%s,它将被替换为前缀为“v”的新的全局版本号。如果信息包含%v,它将被替换为不带前导“v”的新全局版本号。请注意,此占位符插值仅适用于使用默认的“固定”版本控制模式时,因为在独立进行版本控制时没有要插入的“全局”版本。

可以在lerna.json中配置,以及:

{
  "command": {
    "version": {
      "message": "chore(release): publish %s"
    }
  }
}

--no-changelog

lerna version --conventional-commits --no-changelog

当使用 conventional-commits,不生成任何CHANGELOG.md文件

注意:使用此选项时,不能传递--create release。

--no-commit-hooks

默认情况下,lerna version将允许git提交钩子在提交版本更改时运行。传递 --no-commit-hooks用于禁用此行为的提交钩子。

这个选项类似于npm version选项 --commit-hooks钩子,只是颠倒了一下。

--no-git-tag-version

默认情况下,lerna version将提交对package.json文件并标记发布。传递--no-git-tag-version来禁用该行为。

这个选项类似于npm version选项--git-tag-version,只是颠倒了一下。

--no-granular-pathspec

默认情况下,lerna version将git add在版本控制过程中更改的叶包清单(可能还有changelogs)。这将产生相当于git add -- packages/*/package.json,但完全适应了变化。

如果你知道你需要不同的行为,你就会明白传递--no-granular-pathspec来让git命令字面上是git add--。。通过选择此路径规范,必须正确忽略所有机密和生成输出,否则将提交并推送。

在lerna.json中配置此选项最有意义,因为你真的不想把事情搞砸:

{
  "version": "independent",
  "granularPathspec": false
}

根级配置是有意的,因为这也包括了lerna publish中同名的选项。

--no-private

默认情况下,在选择版本、提交和标记发布时,lerna version将包含私有包。--no-private来禁用此行为。

请注意,此选项不排除私有范围的包,只排除那些在其package.json文件 "private": true。

--no-push

默认情况下,lerna version会将已提交和标记的更改推送到配置的git remote。--no-push以禁用此行为。

--preid

lerna version prerelease
# 使用下一个语义预发布版本,例如。
# 1.0.0 => 1.0.1-alpha.0

lerna version prepatch --preid next
# 使用具有特定预发布标识符的下一个语义预发布版本,例如。
# 1.0.0 => 1.0.1-next.0

使用此标志运行时,lerna version将使用指定的prerelease标识符增加prejor、preminor、prepatch或prerelease semver bumps。

--sign-git-commit

此选项类似于同名的npm version选项。

--sign-git-tag

此选项类似于同名的npm version选项。

--force-git-tag

此选项将替换任何现有标记,而不是失败。

--tag-version-prefix

此选项允许提供自定义前缀,而不是默认前缀:v。

请记住,当前必须提供两次:对于version命令和publish命令:

# locally
lerna version --tag-version-prefix=''
# on ci
lerna publish from-git --tag-version-prefix=''

--yes

lerna version --yes
# skips `Are you sure you want to publish these packages?`

使用此标志运行时,lerna版本将跳过所有确认提示。在连续集成(CI)中非常有用,可自动响应发布确认提示。

提示

生成初始变更日志

如果在monorepo激活一段时间后开始使用--conditional commits选项,那么仍然可以使用传统的changelog cli和lerna exec为以前的版本生成变更日志:

# Lerna实际上并不使用传统的changelog cli,因此您需要临时安装它
npm i -D conventional-changelog-cli
# Documentatiional-on: `npx conventchangelog --help`

# fixed versioning (default)
# run in root, then leaves
npx conventional-changelog --preset angular --release-count 0 --outfile ./CHANGELOG.md --verbose
npx lerna exec --concurrency 1 --stream -- 'conventional-changelog --preset angular --release-count 0 --commit-path $PWD --pkg $PWD/package.json --outfile $PWD/CHANGELOG.md --verbose'

# independent versioning
# (no root changelog)
npx lerna exec --concurrency 1 --stream -- 'conventional-changelog --preset angular --release-count 0 --commit-path $PWD --pkg $PWD/package.json --outfile $PWD/CHANGELOG.md --verbose --lerna-package $LERNA_PACKAGE_NAME'

如果使用自定义--changelog预置,则应该在上面的示例中相应地更改--preset值。

Lifecycle Scripts

// preversion:  Run BEFORE bumping the package version.
// version:     Run AFTER bumping the package version, but BEFORE commit.
// postversion: Run AFTER bumping the package version, and AFTER commit.

Lerna will run npm lifecycle scripts during lerna version in the following order:

  • Detect changed packages, choose version bump(s)
  • Run preversion lifecycle in root
  • For each changed package, in topological order (all dependencies before dependents):
    • Run preversion lifecycle
    • Update version in package.json
    • Run version lifecycle
  • Run version lifecycle in root
  • Add changed files to index, if enabled
  • Create commit and tag(s), if enabled
  • For each changed package, in lexical order (alphabetical according to directory structure):
    • Run postversion lifecycle
  • Run postversion lifecycle in root
  • Push commit and tag(s) to remote, if enabled
  • Create release, if enabled