## 1. Project Overview & Quickstart (f/OWNERS)

# Technical Documentation: f/OWNERS

> ℹ️ **Provenance:** Multi-Tier Ingestion · [CodeWiki Reference](https://codewiki.google/github.com/f/OWNERS)

# OWNERS

### Agent Skills & Rules
- Discovered 21 agent rule(s) and prompt configurations.



--- METRICS ---
- Files Extracted: 1
- Estimated Token Budget: ~24 tokens
- Canonical Reference: https://codewiki.google/github.com/f/OWNERS


## 2. Official Technical Reference & Guides (f/website)

## File: lang/en/docs/cli/add.md

---
id: docs_cli_add
guide: docs_cli
layout: guide
additional_reading_tags: ["dependencies"]
---

{% include vars.html %}

Installs a package and any packages that it depends on.

### Adding dependencies <a class="toc" id="toc-adding-dependencies" href="#toc-adding-dependencies"></a>

In general, a package is simply a folder with code and a `package.json` file
that describes the contents. When you want to use another package, you first
need to add it to your dependencies. This means running `yarn add [package-name]`
to install it into your project.

This will also update your `package.json` and your `yarn.lock` so that other
developers working on the project will get the same dependencies as you when
they run `yarn` or `yarn install`.

Most packages will be installed from the [npm registry](https://www.npmjs.com/)
and referred to by simply their package name. For example, `yarn add react`
will install the [`react`](https://www.npmjs.com/package/react) package from
the npm registry.

You can specify versions using one of these:

1. `yarn add package-name` installs the "latest" version of the package.
2. `yarn add package-name@1.2.3` installs a specific version of a package from
  the registry.
3. `yarn add package-name@tag` installs a specific
  ["tag"]({{url_base}}/docs/cli/tag) (e.g. `beta`, `next`, or `latest`).

You can also specify packages from different locations:

1. `yarn add package-name` installs the package from the
  [npm registry](https://www.npmjs.com/) unless you have specified another one
  in your `package.json`.
2. `yarn add file:/path/to/local/folder` installs a package that is on your
  local file system. This is useful to test out other packages of yours that
  haven't been published to the registry.
3. `yarn add file:/path/to/local/tarball.tgz` installs a package from a gzipped
  tarball which could be used to share a package before publishing it.
4. `yarn add <git remote url>` installs a package from a remote git repository.
5. `yarn add <git remote url>#` installs a package from a remote
  git repository at specific git branch, git commit or git tag.
6. `yarn add https://my-project.org/package.tgz` installs a package from a
  remote gzipped tarball.

### Caveats <a class="toc" id="toc-caveats" href="#toc-caveats"></a>

If you have used a package manager like npm previously, you may be looking for
how to add global dependencies.

For the vast majority of packages it is considered a bad practice to have
global dependencies because they are implicit. It is much better to add
all of your dependencies locally so that they are explicit and anyone else
using your project gets the same set of dependencies.

If you are trying to use a CLI tool that has a `bin` you can access these in
your `./node_modules/.bin` directory. You can also use the
[`global`]({{url_base}}/docs/cli/global) command:

```sh
yarn global add <package...>
```

### Commands <a class="toc" id="toc-commands" href="#toc-commands"></a>

##### `yarn add ` <a class="toc" id="toc-yarn-add" href="#toc-yarn-add"></a>

This will install one or more packages in your
[`dependencies`]({{url_base}}/docs/dependency-types#toc-dependencies).

##### `yarn add  [--dev/-D]` <a class="toc" id="toc-yarn-add-dev-d" href="#toc-yarn-add-dev-d"></a>

Using `--dev` or `-D` will install one or more packages in your
[`devDependencies`]({{url_base}}/docs/dependency-types#toc-dev-dependencies).

##### `yarn add  [--peer/-P]` <a class="toc" id="toc-yarn-add-peer-p" href="#toc-yarn-add-peer-p"></a>

Using `--peer` or `-P` will install one or more packages in your
[`peerDependencies`]({{url_base}}/docs/dependency-types#toc-peer-dependencies).

##### `yarn add  [--optional/-O]` <a class="toc" id="toc-yarn-add-optional-o" href="#toc-yarn-add-optional-o"></a>

Using `--optional` or `-O` will install one or more packages in your
[`optionalDependencies`]({{url_base}}/docs/dependency-types#toc-optional-dependencies).

##### `yarn add  [--exact/-E]` <a class="toc" id="toc-yarn-add-exact-e" href="#toc-yarn-add-exact-e"></a>

Using `--exact` or `-E` installs the packages as exact versions. The default is
to use the most recent release with the same major version. For example,
`yarn add foo@1.2.3` would accept version `1.9.1`, but
`yarn add foo@1.2.3 --exact` would only accept version `1.2.3`.

##### `yarn add  [--tilde/-T]` <a class="toc" id="toc-yarn-add-tilde-t" href="#toc-yarn-add-tilde-t"></a>

Using `--tilde` or `-T` installs the most recent release of the packages that
have the same minor version. The default is to use the most recent release with
the same major version. For example, `yarn add foo@1.2.3 --tilde` would accept
`1.2.9` but not `1.3.0`.

---

## File: lang/en/docs/cli/bin.md

---
id: docs_cli_bin
guide: docs_cli
layout: guide
---

{% include vars.html %}

Displays the location of the yarn `bin` folder.

##### `yarn bin` <a class="toc" id="toc-yarn-bin" href="#toc-yarn-bin"></a>

`yarn bin` will print the folder where yarn will install executable files for your package. An example of an executable may be a script that you have defined for your package that can be executed via [`yarn run`]({{url_base}}/docs/cli/run).

---

## File: lang/en/docs/cli/cache.md

---
id: docs_cli_cache
guide: docs_cli
layout: guide
---

##### `yarn cache ls` <a class="toc" id="toc-yarn-cache-ls" href="#toc-yarn-cache-ls"></a>

Yarn stores every package in a global cache in your user directory on the file
system. `yarn cache ls` will print out every cached package.

##### `yarn cache dir` <a class="toc" id="toc-yarn-cache-dir" href="#toc-yarn-cache-dir"></a>

Running `yarn cache dir` will print out the path where yarn's global cache is currently stored.

##### `yarn cache clean` <a class="toc" id="toc-yarn-cache-clean" href="#toc-yarn-cache-clean"></a>

Running this command will clear the global cache. It will be populated again the
next time `yarn` or `yarn install` is run. Additionally, you can specify name of package you want to clean.

### Change the cache path for yarn <a class="toc" id="toc-change-the-cache-path-for-yarn" href="#toc-change-the-cache-path-for-yarn"></a>

Set `cache-folder` config value to configure the cache directory.
```sh
yarn config set cache-folder <path>
```

You can also specify the cache directory by flag `--cache-folder`:
```sh
yarn <command> --cache-folder <path>
```

You can also specify the cache directory by environment variable `YARN_CACHE_FOLDER`:
```sh
YARN_CACHE_FOLDER=<path> yarn <command>
```

---

## File: lang/en/docs/cli/check.md

---
id: docs_cli_check
guide: docs_cli
layout: guide
---

##### `yarn check` <a class="toc" id="toc-yarn-check" href="#toc-yarn-check"></a>

Verifies that versions of the package dependencies in the current project's `package.json` matches that of yarn's lock file.

##### `yarn check --integrity` <a class="toc" id="toc-yarn-check-integrity" href="#toc-yarn-check-integrity"></a>

Verifies that versions and hashed value of the package contents in the project's `package.json` matches that of yarn's lock file. This helps to verify that the package dependencies have not been altered.

---

## File: lang/en/docs/cli/clean.md

---
id: docs_cli_clean
guide: docs_cli
layout: guide
---

Cleans and removes unnecessary files from package dependencies.

##### `yarn clean` <a class="toc" id="toc-yarn-clean" href="#toc-yarn-clean"></a>

The `clean` command frees up space by removing unnecessary files and folders from dependencies. It reduces the number of files in your project's `node_modules` folder which is useful in an environment where packages are checked into version control directly.

Once you run `yarn clean`, Yarn will create a `.yarnclean` file that should be added to version control. Cleaning is then automatically done as part of `yarn install` (or simply `yarn`) and `yarn add`.

*Note: This command is considered for advanced use cases only. Unless you are experiencing issues with the amount of files that are installed as part of `node_modules` it is not recommended to use this command. It uses a heuristic to identify files that may not be needed from a distributed package and may not be entirely safe.*

---

## File: lang/en/docs/cli/config.md

---
id: docs_cli_config
guide: docs_cli
layout: guide
---

Manages the yarn configuration files.

##### `yarn config set <key> <value> [-g|--global]` <a class="toc" id="toc-yarn-config-set-g-global" href="#toc-yarn-config-set-g-global"></a>

Sets the config `key` to a certain `value`.

Example:

```sh
$ yarn config set init-license BSD-2-Clause
yarn config vx.x.x
success Set "init-license" to "BSD-2-Clause".
✨  Done in 0.05s.

```

##### `yarn config get <key>` <a class="toc" id="toc-yarn-config-get" href="#toc-yarn-config-get"></a>

Echoes the value for a given `key` to `stdout`.

Example:

```sh
$ yarn config get init-license
BSD-2-Clause
```

##### `yarn config delete <key>` <a class="toc" id="toc-yarn-config-delete" href="#toc-yarn-config-delete"></a>

Deletes a given `key` from the config.

Example:

```sh
$ yarn config delete test-key
yarn config vx.x.x
success Deleted "test-key".
✨  Done in 0.06s.
```

##### `yarn config list` <a class="toc" id="toc-yarn-config-list" href="#toc-yarn-config-list"></a>

Displays the current configuration.

Example:

```sh
$ yarn config list
yarn config vx.x.x
info yarn config
{ 'version-tag-prefix': 'v',
  'version-git-tag': true,
  'version-git-sign': false,
  'version-git-message': 'v%s',
  'init-version': '1.0.0',
  'init-license': 'MIT',
  'save-prefix': '^',
  'ignore-scripts': false,
  'ignore-optional': true,
  registry: 'https://registry.yarnpkg.com',
  'user-agent': 'yarn/0.15.0 npm/? node/v6.2.1 darwin x64' }
info npm config
{ registry: 'https://registry.npmjs.org/',
  '//localhost:4873/:_authToken': 'some-auth-token' }
✨  Done in 0.05s.

```

---

## File: lang/en/docs/cli/create.md

---
id: docs_cli_create
guide: docs_cli
layout: guide
---

{% include vars.html %}

Creates new projects from any `create-*` starter kits.

##### `yarn create <starter-kit-package> [<args>]` <a class="toc" id="toc-yarn-create" href="#toc-yarn-create"></a>

This command is a shorthand that helps you do two things at once:

* Install `create-<starter-kit-package>` globally, or update the package to the
latest version if it already exists
* Run the executable located in the `bin` field of the starter kit’s `package.json`,
forwarding any `<args>` to it

For example, `yarn create react-app my-app` is equivalent to:

```sh
$ yarn global add create-react-app
$ create-react-app my-app
```

For more information, check out the [relevant blog entry](https://yarnpkg.com/blog/2017/05/12/introducing-yarn/).

---

## File: lang/en/docs/cli/generate-lock-entry.md

---
id: docs_cli_generate_lock_entry
guide: docs_cli
layout: guide
---

Generates a lock file entry.

##### `yarn generate-lock-entry` <a class="toc" id="toc-yarn-generate-lock-entry" href="#toc-yarn-generate-lock-entry"></a>

*Note: This command is considered for advanced use-cases and tooling only. It generates a lock file entry given the current `package.json` manifest file.*

```sh
$ yarn generate-lock-entry
# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
# yarn lockfile v1
yarnpkg@0.14.0:
  version "0.14.0"
  dependencies:
    babel-plugin-transform-inline-imports-commonjs "^1.0.0"
    babel-runtime "^6.0.0"
    bytes "^2.4.0"
    [...]
```

---

## File: lang/en/docs/cli/global.md

---
id: docs_cli_global
guide: docs_cli
layout: guide
---

{% include vars.html %}

Install packages globally on your operating system.

##### `yarn global <add/bin/ls/remove/upgrade> [--prefix]` <a class="toc" id="toc-yarn-global" href="#toc-yarn-global"></a>

`yarn global` is a prefix used for a number of commands like `add`, `bin`, `ls` and `remove`. They behave identically to their normal versions except that they use a global directory to store packages. The `global` command makes binaries available to use on your operating system.

*Note: Unlike the `--global` flag in npm, `global` is a command which must immediately follow `yarn`. Entering `yarn add global package-name` will add the packages named `global` and `package-name` locally instead of adding `package-name` globally.*

This is useful for developer tooling that is not part of any individual project but instead is used for local commands. One such example is [create-react-app](https://github.com/facebookincubator/create-react-app) which can be installed globally like this:

```sh
$ yarn global add create-react-app --prefix /usr/local
# the `create-react-app` command is now available globally:
$ which create-react-app
$ /usr/local/bin/create-react-app
$ create-react-app
````

### Defining install location

`yarn global bin` will output the location where Yarn will install symlinks to your installed binaries. You can configure the base location with `yarn config set prefix <filepath>`. For example, `yarn config set prefix ~/.yarn` will ensure all global packages will have their binaries installed to `~/.yarn/bin`.

Read more about the commands that can be used together with `yarn global`:

- [`yarn add`]({{url_base}}/docs/cli/add): add a package to use in your current package. 
- [`yarn bin`]({{url_base}}/docs/cli/bin): displays the location of the yarn bin folder.
- [`yarn list`]({{url_base}}/docs/cli/list): list installed packages.
- [`yarn remove`]({{url_base}}/docs/cli/remove): remove a package that will no longer be used in your current package.
- [`yarn upgrade`]({{url_base}}/docs/cli/upgrade): upgrades packages to their latest version based on the specified range.

---

## File: lang/en/docs/cli/help.md

---
id: docs_cli_help
guide: docs_cli
layout: guide
---

{% include vars.html %}

Displays help information.

##### `yarn help` <a class="toc" id="toc-yarn-help" href="#toc-yarn-help"></a>

This command shows a list of available commands and flags, each with a brief
explanation on what it does.

---

## File: lang/en/docs/cli/import.md

---
id: docs_cli_import
guide: docs_cli
layout: guide
---

{% include vars.html %}

Generates `yarn.lock` from an existing npm-installed `node_modules` folder.

##### `yarn import` <a class="toc" id="toc-yarn-import" href="#toc-yarn-import"></a>

This command assists the migration of projects currently relying on `npm-shrinkwrap.json`,
minimizing the differences between the lockfile and the existing dependency tree
as best as it can.

### Motivation <a class="toc" id="toc-motivation" href="#toc-motivation"></a>

Many projects currently use `npm shrinkwrap` or check their `node_modules` into
source control because they have fragile dependency trees. These projects can’t
easily migrate to Yarn, because `yarn install` could produce a wildly different
logical dependency tree. Not all trees can be represented by Yarn’s `yarn.lock`,
and some valid trees will be automatically deduped upon install. These nuances
and others present a significant barrier to manual migration.

`yarn import` aims to alleviate this challenge by generating a `yarn.lock` file
using the versions found inside `node_modules` according to normal `require.resolve()`
resolution rules. In cases where the Yarn resolution mechanism can’t satisfy the
existing dependency tree identically, alerts will be made so that you may manually
review the changes. The existing `node_modules` tree will be checked for validity
beforehand, and the resultant lockfile should be `yarn install`able without any
surprises (failed compatibility, unresolvable dependencies, auto-dedupes, etc.)

```sh
$ yarn import
```

```
yarn import vx.x.x
success Folder in sync.
warning Using version "2.2.4" of "lru-cache" instead of "2.7.3" for "ngstorage > grunt > minimatch"
warning Using version "2.0.6" of "readable-stream" instead of "2.2.9" for "ngstorage > karma > chokidar > readdirp"
[...]
success Saved lockfile.
✨  Done in 11.96s.
```

---

## File: lang/en/docs/cli/index.md

---
id: docs_cli_index
guide: docs_cli
layout: guide
---

{% include vars.html %}

Yarn provides a rich set of command-line commands to help you with various aspects of your Yarn package, including installation, administration, publishing, etc.

While all of the available commands are provided here, in alphabetical order, some of the more popular commands are:

- [`yarn add`]({{url_base}}/docs/cli/add): adds a package to use in your current package.
- [`yarn init`]({{url_base}}/docs/cli/init): initializes the development of a package.
- [`yarn install`]({{url_base}}/docs/cli/install): installs all the dependencies defined in a `package.json` file.
- [`yarn publish`]({{url_base}}/docs/cli/publish): publishes a package to a package manager.
- [`yarn remove`]({{url_base}}/docs/cli/remove): removes an unused package from your current package.

## Default Command <a class="toc" id="toc-default-command" href="#toc-default-command"></a>

Running `yarn` with no command will run `yarn install`, passing through any provided flags.

## Concurrency and `--mutex` <a class="toc" id="toc-concurrency-and-mutex" href="#toc-concurrency-and-mutex"></a>
When running multiple instances of yarn as the same user on the same server,
you can ensure only one instance runs at any given time (and avoid conflicts)
by passing the global flag `--mutex` followed by `file` or `network`. 

When using `file` Yarn will write/read a mutex file `.yarn-single-instance` in
the current working directory by default. You can also specify an alternate or
global filename.

```sh
--mutex file
--mutex file:/tmp/.yarn-mutex
```

When using `network` Yarn will create a server at port `31997` by default. You
can also specify an alternate port.

```sh
--mutex network
--mutex network:30330
```