lerna README.md 日本語訳

2017/1/17 v2.0.0-beta.31時点でのREADME.mdのほぼGoogle翻訳です。勝手にやったのでまずかったら消します！

A tool for managing JavaScript projects with multiple packages.

About

Splitting up large codebases into separate independently versioned packages is extremely useful for code sharing. However, making changes across many repositories is messy and difficult to track, and testing across repositories gets complicated really fast.

大規模なコードベースを別々のバージョン管理されたパッケージに分割することは、コード共有に非常に便利です。 しかし、多くのリポジトリをまたいだ変更を加えるのは面倒で、トラッキングも難しく、リポジトリをまたいだテストは非常に複雑になります。

To solve these (and many other) problems, some projects will organize their codebases into multi-package repositories (sometimes called monorepos). Projects like Babel, React, Angular, Ember, Meteor, Jest, and many others develop all of their packages within a single repository.

これらの問題を解決するために、いくつかのプロジェクトはコードベースをマルチパッケージレポジトリ（時にはmonorepoと呼ばれる）に編成します。 Babel、React、Angular、Ember、Meteor、Jestなどのプロジェクトは、単一のリポジトリ内ですべてのパッケージを開発します。

Lerna is a tool that optimizes the workflow around managing multi-package repositories with git and npm.

Lernaは、マルチパッケージリポジトリの管理に関するワークフローをgitとnpmで最適化するツールです。

What does a Lerna repo look like?

There's actually very little to it. You have a file system that looks like this:

実際の構成要素は少なく、以下のようなディレクトリ構造になります。

my-lerna-repo/
  package.json
  packages/
    package-1/
      package.json
    package-2/
      package.json

What can Lerna do?

The two primary commands in Lerna are lerna bootstrap and lerna publish.

Lernaの2つの主なコマンドは lerna bootstrapと lerna publishです。

bootstrap will link dependencies in the repo together.
publish will help publish any updated packages.

bootstrapはリポジトリの依存関係をまとめてリンクします。
publishは更新されたパッケージを公開するのに役立ちます。

Getting Started

The instructions below are for Lerna 2.x which is currently in beta.
We recommend using it instead of 1.x for a new Lerna project. Check the wiki if you need to see the 1.x README.

以下の手順は現在ベータ版のLerna 2.x用です。
新しいLernaプロジェクトには、1.xではなく2.xを使用することをお勧めします。 1.x READMEが必要な場合は、wiki を確認してください。

Let's start by installing Lerna globally with npm.

npm でLernaをグローバルにインストールしてみましょう。

$ npm install --global lerna

Next we'll create a new git repository:

次に、新しいgit リポジトリを作成します。

$ git init lerna-repo
$ cd lerna-repo

And now let's turn it into a Lerna repo:

そして、それをLernaのレポに変えましょう：

$ lerna init

Your repository should now look like this:

リポジトリは次のようになります。

lerna-repo/
  package.json
  lerna.json

This will create a lerna.json configuration file as well as a packages folder.

これは lerna.json設定ファイルと packagesフォルダを作成します。

How it works

Lerna allows you to manage your project using one of two modes: Fixed or Independent.

Lernaでは、FixedまたはIndependentの2つのモードのいずれかを使用してプロジェクトを管理できます。

Fixed/Locked mode (default)

Fixed mode Lerna projects operate on a single version line. The version is kept in the lerna.json file at the root of your project under the version key. When you run lerna publish, if a module has been updated since the last time a release was made, it will be updated to the new version you're releasing. This means that you only publish a new version of a package when you need to.

FixedモードLernaプロジェクトは、単一のバージョンライン上で動作します。 バージョンは、プロジェクトのルートにある lerna.jsonファイルの versionキーの下に保持されます。 lerna publishを実行すると、モジュールが最後にリリースされてから更新されていれば、リリースしようとしている新しいバージョンに更新されます。 これは、必要に応じて新しいバージョンのパッケージのみを公開することを意味します。

This is the mode that Babel is currently using. Use this if you want to automatically tie all package versions together. One issue with this approach is that a major change in any package will result in all packages having a new major version.

これは Babel が現在使用しているモードです。 自動的にすべてのパッケージバージョンを結合する場合は、これを使用します。 このアプローチの1つの問題は、一つでもメジャーな変更があるパッケージがあれば、すべてのパッケージが新しいメジャーバージョンを持つことになります。

Independent mode (--independent)

Independent mode Lerna projects allows maintainers to increment package versions independently of each other. Each time you publish, you will get a prompt for each package that has changed to specify if it's a patch, minor, major or custom change.

IndependentモードLernaプロジェクトは、メンテナがパッケージのバージョンを互いに独立して管理することを可能にします。 パブリッシュするたびに、パッチ、マイナー、メジャー、またはカスタムの変更を指定するために変更された各パッケージのプロンプトが表示されます。

Independent mode allows you to more specifically update versions for each package and makes sense for a group of components. Combining this mode with something like semantic-release would make it less painful. (There is work on this already at atlassian/lerna-semantic-release).

Independentモードでは、各パッケージのバージョンをより具体的に更新できるため、コンポーネントのグループを管理するのに適しています。 このモードを semantic-release のようなものと組み合わせると、苦痛が少なくなります。 （atlassian/lerna-semantic-releaseは既にそのように進めています）。

The version key in lerna.json is ignored in independent mode.

lerna.jsonの versionキーは、Independentモードでは無視されます。

Frequently asked questions

See FAQ.md.
FAQ.md を参照。

Commands

init

$ lerna init

Create a new Lerna repo or upgrade an existing repo to the current version of Lerna.

新しいLernaレポを作成するか、既存のレポを現在のバージョンのLernaにアップグレードします。

Lerna assumes the repo has already been initialized with git init.

Lernaはrepoが git initで既に初期化されていると仮定します。

When run, this command will:

実行すると、次のコマンドが実行されます。

1. Add lerna as a devDependency in package.json if it doesn't already exist.
2. Create a lerna.json config file to store the version number.

1. lernaを devDependency として package.jsonに追加します（存在しない場合）。
2. versionを保持するためlerna.json設定ファイルを作成します。

Example output on a new git repo:

新しいgit repoの出力例：

> lerna init
$ Lerna v2.0.0-beta.31
$ Creating packages directory.
$ Updating package.json.
$ Creating lerna.json.
$ Successfully created Lerna files

--independent, -i

$ lerna init --independent

This flag tells Lerna to use independent versioning mode.

このフラグは、LernaにIndependentバージョン管理モードを使用するよう指示します。

bootstrap

$ lerna bootstrap

Bootstrap the packages in the current Lerna repo.
Installs all of their dependencies and links any cross-dependencies.

パッケージを現在のLernaリポジトリにブートストラップします。
すべての依存関係をインストールし、相互依存関係をリンクします。

When run, this command will:

実行すると、次のコマンドが実行されます。

1. npm install all external dependencies of each package.
2. Symlink together all Lerna packages that are dependencies of each other.
3. npm prepublish all bootstrapped packages.

1. 各パッケージのすべての外部依存関係を npm installします。
2. 互いの依存関係であるすべてのLerna packagesをシンボリックリンクします。
3. すべてのブートストラップされたパッケージをnpm prepublishします。

lerna bootstrap respects the --ignore and --scope flags (see Flags).

lerna bootstrapは --ignoreと --scopeフラグを尊重します（Flags参照）。

How bootstrap works

Let's use babel as an example.

例として babelを使ってみましょう。

• babel-generator and source-map (among others) are dependencies of babel-core.
• babel-core's package.json lists both these packages as keys in dependencies, as shown below.

• babel-generatorと source-mapは babel-coreの依存関係です。
• babel-coreのpackage.json には、これら両方のパッケージ 以下に示すようにdependenciesのキーとして使用します。

// babel-core package.json
{
  "name": "babel-core",
  ...
  "dependencies": {
    ...
    "babel-generator": "^6.9.0",
    ...
    "source-map": "^0.5.0"
  }
}

• Lerna checks if each dependency is also part of the Lerna repo.
  • In this example, babel-generator is a dependency, while source-map is not.
  • source-map is npm installed like normal.
• packages/babel-core/node_modules/babel-generator symlinks to packages/babel-generator
• This allows nested directory imports

• Lernaは各依存関係もLernaリポジトリの一部であるかどうかをチェックします。
  • この例では、 babel-generatorは依存関係ですが、 source-mapは依存関係ではありません。
  • source-mapは通常と同様に npm installされます。
• packages/babel-core/node_modules/babel-generatorはpackages/babel-generatorへのシンボリックリンクです。
• これにより、ネストされたディレクトリのインポートが可能になります。

Note: Circular dependencies result in circular symlinks which may impact your editor/IDE.

**注意：**循環依存関係は、あなたのエディタ/ IDEに影響するかもしれない循環的なシンボリックリンクをもたらします。

Webstorm locks up when circular symlinks are present. To prevent this, add node_modules to the list of ignored files and folders in Preferences | Editor | File Types | Ignored files and folders.

Webstormは、環状のシンボリックリンクが存在するとロックします。 これを防ぐには、 Preferences | Editor | File Types | Ignored files and foldersから node_modulesを無視するファイルとフォルダのリストに追加してください。

publish

$ lerna publish

Publish packages in the current Lerna project. When run, this command does the following:

現在のLernaプロジェクトにあるパッケージを公開します。 実行すると、このコマンドが以下の処理を行います。

Creates a new release of the packages that have been updated.
Prompts for a new version.
Creates a new git commit/tag in the process of publishing to npm.

更新のあったパッケージの新しいリリースを作成します。
新しいバージョンのプロンプトを表示します。
npmにパブリッシュする過程で、新しいgitコミット/タグを作成します。

More specifically, this command will:

1. Publish each module in packages that has been updated since the last version to npm with the dist-tag lerna-temp.
2. Run the equivalent of lerna updated to determine which packages need to be published.
3. If necessary, increment the version key in lerna.json.
4. Update the package.json of all updated packages to their new versions.
5. Update all dependencies of the updated packages with the new versions.
6. Create a new git commit and tag for the new version.
7. Publish updated packages to npm.
8. Once all packages have been published, remove the lerna-temp tags and add the tags to latest.

具体的には、次のコマンドを実行します。

1. dist-tag lerna-tempを使用して、最後のバージョン以降に更新された packagesの各モジュールをnpmに公開します。

   1. lerna updatedに相当するものを実行して、公開するパッケージを決定します。
   2. 必要に応じて、 lerna.jsonのversionキーをインクリメントします。
   3. すべての更新パッケージの package.jsonを新しいバージョンに更新します。
   4. 更新されたパッケージのすべての依存関係を新しいバージョンに更新します。
   5. 新しいバージョンの新しいgitコミットとタグを作成します。
   6. 更新されたパッケージをnpmに公開します。

2.すべてのパッケージが公開されたら、 lerna-temp タグを削除し、タグをlatestに追加します。

A temporary dist-tag is used at the start to prevent the case where only some of the packages are published; this can cause issues for users installing a package that only has some updated packages.

最初に一時的なdist-tagを使用して、一部のパッケージのみが公開されることを防ぎます。 これにより、更新パッケージがいくつかしかないパッケージをインストールするユーザーに問題が発生する可能性があります。

Lerna won't publish packages which are marked as private ("private": true in the package.json).

Lernaはプライベートとしてマークされた（package.jsonの"private": trueがセットされている）パッケージを公開しません。

--npm-tag [tagname]

$ lerna publish --npm-tag=next

When run with this flag, publish will publish to npm with the given npm dist-tag (defaults to latest).

This option can be used to publish a prerelease or beta version.

Note: the latest tag is the one that is used when a user runs npm install my-package.
To install a different tag, a user can run npm install my-package@prerelease.

--canary, -c

$ lerna publish --canary

When run with this flag, publish publishes packages in a more granular way (per commit). Before publishing to npm, it creates the new version tag by taking the current version and appending the current git sha (ex: 1.0.0-alpha.81e3b443).

The intended use case for this flag is a per commit level release or nightly release.

--skip-git

$ lerna publish --skip-git

When run with this flag, publish will publish to npm without running any of the git commands.

Only publish to npm; skip committing, tagging, and pushing git changes (this only affects publish).

--skip-npm

$ lerna publish --skip-npm

When run with this flag, publish will update all package.json package
versions and dependency versions, but it will not actually publish the
packages to npm.

This is useful as a workaround for an npm
issue which prevents README updates
from appearing on npmjs.com when published via Lerna. When publishing with
README changes, use --skip-npm and do the final npm publish by hand for
each package.

This flag can be combined with --skip-git to just update versions and
dependencies, without committing, tagging, pushing or publishing.

Only update versions and dependencies; don't actually publish (this only affects publish).

--force-publish [packages]

$ lerna publish --force-publish=package-2,package-4
# force publish all packages
$ lerna publish --force-publish=*

When run with this flag, publish will force publish the specified packages (comma-separated) or all packages using *.

This will skip the lerna updated check for changed packages and forces a package that didn't have a git diff change to be updated.

--yes

$ lerna publish --canary --yes
# skips `Are you sure you want to publish the above changes?`

When run with this flag, publish will skip all confirmation prompts.
Useful in Continuous integration (CI) to automatically answer the publish confirmation prompt.

--repo-version

$ lerna publish --repo-version 1.0.1
# applies version and skips `Select a new version for...` prompt

When run with this flag, publish will skip the version selection prompt and use the specified version.
Useful for bypassing the user input prompt if you already know which version to publish.

updated

$ lerna updated

Check which packages have changed since the last release (the last git tag).

最後のリリース（最後のgitタグ）からどのパッケージが変更されたかを確認します。

Lerna determines the last git tag created and runs git diff --name-only v6.8.1 to get all files changed since that tag. It then returns an array of packages that have an updated file.

Lernaは作成された最後のgitタグを決定し、 git diff -name-only v6.8.1を実行して、そのタグ以降に変更されたすべてのファイルを取得します。 次に、更新されたファイルを持つパッケージの配列を返します。

clean

$ lerna clean

Remove the node_modules directory from all packages.

lerna clean respects the --ignore and --scope flags (see Flags).

すべてのパッケージから node_modulesディレクトリを削除します。

lerna cleanは --ignoreと --scopeフラグを尊重します（Flags参照）。

diff

$ lerna diff [package?]

$ lerna diff
# diff a specific package
$ lerna diff package-name

Diff all packages or a single package since the last release.

Similar to lerna updated. This command runs git diff.

前回のリリースからのすべてまたは単一のパッケージのDiffを表示します。

lerna updatedと同様です。 このコマンドは git diffを実行します。

ls

$ lerna ls

List all of the public packages in the current Lerna repo.

lerna ls respects the --ignore and --scope flags (see Flags).

現在のLernaリポジトリの公開パッケージをすべて一覧表示します。

lerna lsは --ignoreと --scopeフラグを尊重します（Flagsを参照）。

run

$ lerna run [script] # runs npm run my-script in all packages that have it
$ lerna run test
$ lerna run build

Run an npm script in each package that contains that script.

lerna run respects the --concurrency, --scope and ignore flags (see Flags).

スクリプトを含む各パッケージでnpm scriptを実行します。

lerna runは--concurrency、 --scopeとignoreフラグを尊重します（Flags参照）。

$ lerna run --scope my-component test

exec

$ lerna exec -- [command] # runs the command in all packages
$ lerna exec -- rm -rf ./node_modules
$ lerna exec -- protractor conf.js

Run an arbitrary command in each package.

lerna exec respects the --concurrency, --scope and --ignore flags (see Flags).

各パッケージで任意のコマンドを実行します。

lerna execは--concurrency、 --scope、--ignoreフラグを尊重します（Flagsを参照）。

$ lerna exec --scope my-component -- ls -la

Hint: The commands are spawned in parallel, using the concurrency given.
The output is piped through, so not deterministic.
If you want to run the command in one package after another, use it like this:

ヒント：コマンドは、並行処理を使用して並行して生成されます。
出力はパイプスルーされているため、確定的ではありません。
コマンドを1つのパッケージで別のパッケージの後に実行する場合は、次のように使用します。

$ lerna exec --concurrency 1 -- ls -la

import

$ lerna import <path-to-external-repository>

Import the package at <path-to-external-repository>, with commit history, into packages/<directory-name>. Original commit authors, dates and messages are preserved. Commits are applied to the current branch.

<path-to-external-repository>でコミットの履歴とともにパッケージをpackages / <directory-name>にインポートします。 オリジナルコミットの著者、日付、メッセージは保存されます。 コミットは現在のブランチに適用されます。

This is useful for gathering pre-existing standalone packages into a Lerna repo. Each commit is modified to make changes relative to the package directory. So, for example, the commit that added package.json will instead add packages/<directory-name>/package.json.

これは既存のスタンドアロンパッケージをLernaリポジトリに集めるのに便利です。 各コミットは、パッケージディレクトリに関連して変更を加えるように変更されます。 たとえば、 package.jsonを追加したコミットはpackages / <directory-name> / package.jsonを追加します。

Misc

Lerna will log to a lerna-debug.log file (same as npm-debug.log) when it encounters an error running a command.

Lerna also has support for scoped packages.

Running lerna without arguments will show all commands/options.

lerna.json

{
  "lerna": "2.0.0-beta.31",
  "version": "1.1.3",
  "publishConfig": {
    "ignore": [
      "ignored-file",
      "*.md"
    ]
  },
  "bootstrapConfig": {
    "ignore": "component-*"
  },
  "packages": ["packages/*"]
}

• lerna: the current version of Lerna being used.
• version: the current version of the repository.
• publishConfig.ignore: an array of globs that won't be included in lerna updated/publish. Use this to prevent publishing a new version unnecessarily for changes, such as fixing a README.md typo.
• bootstrapConfig.ignore: an glob that won't be bootstrapped when running the lerna bootstrap command.
• bootstrapConfig.scope: an glob that restricts which packages will be bootstrapped when running the lerna bootstrap command.
• packages: Array of globs to use as package locations.

• lerna：現在使われているLernaのバージョンです。
• version：リポジトリの現在のバージョンです。
• publishConfig.ignore： lerna updated / publishに含まれないglobの配列です。 README.mdの入力ミスを修正するなど、変更のために新しいバージョンを不必要に発行しないようにするためにこれを使います。
• bootstrapConfig.ignore： lerna bootstrapコマンドの実行時にブートストラップされないglobです。
• bootstrapConfig.scope： lerna bootstrapコマンドの実行時にどのパッケージがブートストラップされるかを制限するglobです。
• packages：パッケージの場所として使用するglobの配列です。

Common devDependencies

Most devDependencies can be pulled up to the root of a Lerna repo.

This has a few benefits:

ほとんどの devDependenciesは、Lernaリポジトリのルートまで引き上げることができます。

これにはいくつかの利点があります。

• All packages use the same version of a given dependency
• Can keep dependencies at the root up-to-date with an automated tool such as GreenKeeper
• Dependency installation time is reduced
• Less storage is needed

• すべてのパッケージが同じ依存関係の同じバージョンを使用します。
• GreenKeeperのような自動ツールを使用して、ルートの依存関係を最新の状態に保つことができます。
• 依存関係のインストール時間が短縮されます。
• ストレージが少なくて済みます。

Note that devDependencies providing "binary" executables that are used by npm scripts still need to be installed directly in each package where they're used.

npmスクリプトによって使用される"バイナリ"実行可能ファイルを提供する devDependenciesは、それが使用されている各パッケージに直接インストールする必要があることに注意してください。

For example the nsp dependency is necessary in this case for lerna run nsp (and npm run nsp within the package's directory) to work correctly:

例えば lerna run nsp（そしてパッケージのディレクトリ内の npm run nsp）が正しく動作するためには、 nsp依存関係が必要です：

{
  "scripts": {
    "nsp": "nsp"
  },
  "devDependencies": {
    "nsp": "^2.3.3"
  }
}

Flags

--concurrency

How many threads to use when Lerna parallelizes the tasks (defaults to 4)

$ lerna publish --concurrency 1

--scope [glob]

Scopes a command to a subset of packages.

$ lerna exec --scope my-component -- ls -la

$ lerna run --scope toolbar-* test

--ignore [glob]

Excludes a subset of packages when running a command.

$ lerna bootstrap --ignore component-*

The ignore flag, when used with the bootstrap command, can also be set in lerna.json under the bootstrapConfig key. The command-line flag will take precendence over this option.

Example

{
  "lerna": "2.0.0-beta.31",
  "version": "0.0.0",
  "bootstrapConfig": {
    "ignore": "component-*"
  }
}

Hint: The glob is matched against the package name defined in package.json,
not the directory name the package lives in.

--only-explicit-updates

Only will bump versions for packages that have been updated explicitly rather than cross-dependencies.

This may not make sense for a major version bump since other packages that depend on the updated packages wouldn't be updated.

$ lerna updated --only-explicit-updates
$ lerna publish --only-explicit-updates

Ex: in Babel, babel-types is depended upon by all packages in the monorepo (over 100). However, Babel uses ^ for most of it's dependencies so it isn't necessary to bump the versions of all packages if only babel-types is updated. This option allows only the packages that have been explicitly updated to make a new version.

--loglevel [silent|error|warn|success|info|verbose|silly]

What level of logs to report. On failure, all logs are written to lerna-debug.log in the current working directory.

Any logs of a higher level than the setting are shown. The default is "info".