Update docs for bun.lock (#16585)

bench/install/README.md

@@ -23,7 +23,7 @@ $ hyperfine --prepare 'rm -rf node_modules' --runs 1 'bun install' 'pnpm install
 To run the benchmark with offline mode but without lockfiles:
 
 ```sh
-$ hyperfine --prepare 'rm -rf node_modules' --warmup 1 'rm bun.lockb && bun install' 'rm pnpm-lock.yaml && pnpm install --prefer-offline' 'rm yarn.lock && yarn --offline' 'rm package-lock.json && npm install --prefer-offline'
+$ hyperfine --prepare 'rm -rf node_modules' --warmup 1 'rm bun.lock && bun install' 'rm pnpm-lock.yaml && pnpm install --prefer-offline' 'rm yarn.lock && yarn --offline' 'rm package-lock.json && npm install --prefer-offline'
 ```
 
 ##

docs/cli/bun-install.md

@@ -95,7 +95,7 @@ disableManifest = false
 [install.lockfile]
 
 # Print a yarn v1 lockfile
-# Note: it does not load the lockfile, it just converts bun.lockb into a yarn.lock
+# Note: it does not load the lockfile, it just converts bun.lock into a yarn.lock
 print = "yarn"
 
 # Save the lockfile to disk
@@ -170,9 +170,9 @@ Bun stores installed packages from npm in `~/.bun/install/cache/${name}@${versio
 
 When the `node_modules` folder exists, before installing, Bun checks if the `"name"` and `"version"` in `package/package.json` in the expected node_modules folder matches the expected `name` and `version`. This is how it determines whether it should install. It uses a custom JSON parser which stops parsing as soon as it finds `"name"` and `"version"`.
 
-When a `bun.lockb` doesn’t exist or `package.json` has changed dependencies, tarballs are downloaded & extracted eagerly while resolving.
+When a `bun.lock` doesn’t exist or `package.json` has changed dependencies, tarballs are downloaded & extracted eagerly while resolving.
 
-When a `bun.lockb` exists and `package.json` hasn’t changed, Bun downloads missing dependencies lazily. If the package with a matching `name` & `version` already exists in the expected location within `node_modules`, Bun won’t attempt to download the tarball.
+When a `bun.lock` exists and `package.json` hasn’t changed, Bun downloads missing dependencies lazily. If the package with a matching `name` & `version` already exists in the expected location within `node_modules`, Bun won’t attempt to download the tarball.
 
 ## Platform-specific dependencies?
 
@@ -184,23 +184,9 @@ Peer dependencies are handled similarly to yarn. `bun install` will automaticall
 
 ## Lockfile
 
-`bun.lockb` is Bun’s binary lockfile format.
+`bun.lock` is Bun’s lockfile format. See [our blogpost about the text lockfile](https://bun.sh/blog/bun-lock-text-lockfile).
 
-## Why is it binary?
-
-In a word: Performance. Bun’s lockfile saves & loads incredibly quickly, and saves a lot more data than what is typically inside lockfiles.
-
-## How do I inspect it?
-
-For now, the easiest thing is to run `bun install -y`. That prints a Yarn v1-style yarn.lock file.
-
-## What does the lockfile store?
-
-Packages, metadata for those packages, the hoisted install order, dependencies for each package, what packages those dependencies resolved to, an integrity hash (if available), what each package was resolved to and which version (or equivalent).
-
-## Why is it fast?
-
-It uses linear arrays for all data. [Packages](https://github.com/oven-sh/bun/blob/be03fc273a487ac402f19ad897778d74b6d72963/src/install/install.zig#L1825) are referenced by an auto-incrementing integer ID or a hash of the package name. Strings longer than 8 characters are de-duplicated. Prior to saving on disk, the lockfile is garbage-collected & made deterministic by walking the package tree and cloning the packages in dependency order.
+Prior to Bun 1.2, the lockfile was binary and called `bun.lockb`. Old lockfiles can be upgraded to the new format by running `bun install --save-text-lockfile --frozen-lockfile --lockfile-only`, and then deleting `bun.lockb`.
 
 ## Cache
 

docs/cli/install.md

@@ -33,7 +33,7 @@ Running `bun install` will:
 
 - **Install** all `dependencies`, `devDependencies`, and `optionalDependencies`. Bun will install `peerDependencies` by default.
 - **Run** your project's `{pre|post}install` and `{pre|post}prepare` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies.
-- **Write** a `bun.lockb` lockfile to the project root.
+- **Write** a `bun.lock` lockfile to the project root.
 
 ## Logging
 
@@ -136,13 +136,13 @@ To install in production mode (i.e. without `devDependencies` or `optionalDepend
 $ bun install --production
 ```
 
-For reproducible installs, use `--frozen-lockfile`. This will install the exact versions of each package specified in the lockfile. If your `package.json` disagrees with `bun.lockb`, Bun will exit with an error. The lockfile will not be updated.
+For reproducible installs, use `--frozen-lockfile`. This will install the exact versions of each package specified in the lockfile. If your `package.json` disagrees with `bun.lock`, Bun will exit with an error. The lockfile will not be updated.
 
 ```bash
 $ bun install --frozen-lockfile
 ```
 
-For more information on Bun's binary lockfile `bun.lockb`, refer to [Package manager > Lockfile](https://bun.sh/docs/install/lockfile).
+For more information on Bun's lockfile `bun.lock`, refer to [Package manager > Lockfile](https://bun.sh/docs/install/lockfile).
 
 ## Omitting dependencies
 

docs/guides/ecosystem/docker.md

@@ -22,12 +22,12 @@ WORKDIR /usr/src/app
 # this will cache them and speed up future builds
 FROM base AS install
 RUN mkdir -p /temp/dev
-COPY package.json bun.lockb /temp/dev/
+COPY package.json bun.lock /temp/dev/
 RUN cd /temp/dev && bun install --frozen-lockfile
 
 # install with --production (exclude devDependencies)
 RUN mkdir -p /temp/prod
-COPY package.json bun.lockb /temp/prod/
+COPY package.json bun.lock /temp/prod/
 RUN cd /temp/prod && bun install --frozen-lockfile --production
 
 # copy node_modules from temp directory

docs/guides/ecosystem/render.md

@@ -53,7 +53,7 @@ app.listen(port, () => {
 Commit your changes and push to GitHub.
 
 ```sh
-$ git add app.ts bun.lockb package.json
+$ git add app.ts bun.lock package.json
 $ git commit -m "Create simple Express app"
 $ git push origin main
 ```

docs/guides/install/from-npm-install-to-bun-install.md

@@ -7,7 +7,7 @@ name: Migrate from npm install to bun install
 We've put a lot of work into making sure that the migration path from `npm install` to `bun install` is as easy as running `bun install` instead of `npm install`.
 
 - **Designed for Node.js & Bun**: `bun install` installs a Node.js compatible `node_modules` folder. You can use it in place of `npm install` for Node.js projects without any code changes and without using Bun's runtime.
-- **Automatically converts `package-lock.json`** to bun's `bun.lockb` lockfile format, preserving your existing resolved dependency versions without any manual work on your part. You can secretly use `bun install` in place of `npm install` at work without anyone noticing.
+- **Automatically converts `package-lock.json`** to bun's `bun.lock` lockfile format, preserving your existing resolved dependency versions without any manual work on your part. You can secretly use `bun install` in place of `npm install` at work without anyone noticing.
 - **`.npmrc` compatible**: bun install reads npm registry configuration from npm's `.npmrc`, so you can use the same configuration for both npm and Bun.
 - **Hardlinks**: On Windows and Linux, `bun install` uses hardlinks to conserve disk space and install times.
 

docs/guides/install/trusted.md

@@ -37,7 +37,7 @@ Once this is added, run a fresh install. Bun will re-install your dependencies a
 
 ```sh
 $ rm -rf node_modules
-$ rm bun.lockb
+$ rm bun.lock
 $ bun install
 ```
 

docs/guides/install/yarnlock.md

@@ -1,5 +1,5 @@
 ---
-name: Generate a human-readable lockfile
+name: Generate a yarn-compatible lockfile
 ---
 
 {% callout %}
@@ -8,11 +8,7 @@ Bun v1.1.39 introduced `bun.lock`, a JSONC formatted lockfile. `bun.lock` is hum
 
 ---
 
-By default Bun generates a binary `bun.lockb` file when you run `bun install`. In some cases, it's preferable to generate a human-readable lockfile instead.
-
----
-
-Use the `--yarn` flag to generate a Yarn-compatible `yarn.lock` file (in addition to `bun.lockb`).
+Use the `--yarn` flag to generate a Yarn-compatible `yarn.lock` file (in addition to `bun.lock`).
 
 ```sh
 $ bun install --yarn
@@ -29,7 +25,7 @@ print = "yarn"
 
 ---
 
-To print a Yarn lockfile to your console without writing it to disk, just "run" your `bun.lockb` with `bun`.
+To print a Yarn lockfile to your console without writing it to disk, "run" your `bun.lockb` with `bun`.
 
 ```sh
 $ bun bun.lockb

docs/install/index.md

@@ -41,7 +41,7 @@ Running `bun install` will:
 
 - **Install** all `dependencies`, `devDependencies`, and `optionalDependencies`. Bun will install `peerDependencies` by default.
 - **Run** your project's `{pre|post}install` scripts at the appropriate time. For security reasons Bun _does not execute_ lifecycle scripts of installed dependencies.
-- **Write** a `bun.lockb` lockfile to the project root.
+- **Write** a `bun.lock` lockfile to the project root.
 
 To install in production mode (i.e. without `devDependencies`):
 

docs/install/lockfile.md

@@ -1,53 +1,10 @@
-Running `bun install` will create a binary lockfile called `bun.lockb`.
+Running `bun install` will create a lockfile called `bun.lock`.
 
-#### Why is it binary?
+https://bun.sh/blog/bun-lock-text-lockfile
 
-In a word: Performance. Bun’s lockfile saves & loads incredibly quickly, and saves a lot more data than what is typically inside lockfiles.
+#### Should it be committed to git?
 
-#### How do I inspect Bun's lockfile?
-
-Run `bun install -y` to generate a Yarn-compatible `yarn.lock` (v1) that can be inspected more easily.
-
-#### How do I `git diff` Bun's lockfile?
-
-Add the following to your local or global `.gitattributes` file:
-
-```
-*.lockb binary diff=lockb
-```
-
-Then add the following to your local git config with:
-
-```sh
-$ git config diff.lockb.textconv bun
-$ git config diff.lockb.binary true
-```
-
-Or to your global git config (system-wide) with the `--global` option:
-
-```sh
-$ git config --global diff.lockb.textconv bun
-$ git config --global diff.lockb.binary true
-```
-
-**Why this works:**
-
-- `textconv` tells git to run `bun` on the file before diffing
-- `binary` tells git to treat the file as binary (so it doesn't try to diff it line-by-line)
-
-Running `bun` on a lockfile will print a human-readable diff. So we just need to tell `git` to run `bun` on the lockfile before diffing it.
-
-#### Platform-specific dependencies?
-
-Bun stores normalized `cpu` and `os` values from npm in the lockfile, along with the resolved packages. It skips downloading, extracting, and installing packages disabled for the current target at runtime. This means the lockfile won’t change between platforms/architectures even if the packages ultimately installed do change.
-
-#### What does Bun's lockfile store?
-
-Packages, metadata for those packages, the hoisted install order, dependencies for each package, what packages those dependencies resolved to, an integrity hash (if available), what each package was resolved to, and which version (or equivalent).
-
-#### Why is Bun's lockfile fast?
-
-It uses linear arrays for all data. [Packages](https://github.com/oven-sh/bun/blob/be03fc273a487ac402f19ad897778d74b6d72963/src/install/install.zig#L1825) are referenced by an auto-incrementing integer ID or a hash of the package name. Strings longer than 8 characters are de-duplicated. Prior to saving on disk, the lockfile is garbage-collected & made deterministic by walking the package tree and cloning the packages in dependency order.
+Yes
 
 #### Generate a lockfile without installing?
 
@@ -69,7 +26,7 @@ To install without creating a lockfile:
 $ bun install --no-save
 ```
 
-To install a Yarn lockfile _in addition_ to `bun.lockb`.
+To install a Yarn lockfile _in addition_ to `bun.lock`.
 
 {% codetabs %}
 
@@ -79,42 +36,15 @@ $ bun install --yarn
 
 ```toml#bunfig.toml
 [install.lockfile]
-# whether to save a non-Bun lockfile alongside bun.lockb
+# whether to save a non-Bun lockfile alongside bun.lock
 # only "yarn" is supported
 print = "yarn"
 ```
 
 {% /codetabs %}
 
-### Text-based lockfile
-
-Bun v1.1.39 introduced `bun.lock`, a JSONC formatted lockfile. `bun.lock` is human-readable and git-diffable without configuration, at [no cost to performance](https://bun.sh/blog/bun-lock-text-lockfile#cached-bun-install-gets-30-faster).
-
-To generate the lockfile, use `--save-text-lockfile` with `bun install`. You can do this for new projects and existing projects already using `bun.lockb` (resolutions will be preserved).
-
-```bash
-$ bun install --save-text-lockfile
-$ head -n3 bun.lock
-{
-  "lockfileVersion": 0,
-  "workspaces": {
-```
-
-Once `bun.lock` is generated, Bun will use it for all subsequent installs and updates through commands that read and modify the lockfile. If both lockfiles exist, `bun.lock` will be chosen over `bun.lockb`.
+#### Text-based lockfile
 
-Bun v1.2.0 will switch the default lockfile format to `bun.lock`.
-
-{% details summary="Configuring lockfile" %}
-
-```toml
-[install.lockfile]
-
-# whether to save the lockfile to disk
-save = true
-
-# whether to save a non-Bun lockfile alongside bun.lockb
-# only "yarn" is supported
-print = "yarn"
-```
+Bun v1.2 changed the default lockfile format to the text-based `bun.lock`. Existing binary `bun.lockb` lockfiles can be migrated to the new format by running `bun install --save-text-lockfile --frozen-lockfile --lockfile-only` and deleting `bun.lockb`.
 
-{% /details %}
+More information about the new lockfile format can be found on [our blogpost](https://bun.sh/blog/bun-lock-text-lockfile).

docs/install/workspaces.md

@@ -6,7 +6,7 @@ It's common for a monorepo to have the following structure:
 tree
 <root>
 ├── README.md
-├── bun.lockb
+├── bun.lock
 ├── package.json
 ├── tsconfig.json
 └── packages

docs/nav.ts

@@ -191,7 +191,7 @@ export default {
     }),
     page("install/lockfile", "Lockfile", {
       description:
-        "Bun's binary lockfile `bun.lockb` tracks your resolved dependency tree, making future installs fast and repeatable.",
+        "Bun's lockfile `bun.lock` tracks your resolved dependency tree, making future installs fast and repeatable.",
     }),
     page("install/registries", "Scopes and registries", {
       description: "How to configure private scopes and custom package registries.",

docs/runtime/autoimport.md

@@ -14,7 +14,7 @@ The first time you run this script, Bun will auto-install `"foo"` and cache it.
 
 To determine which version to install, Bun follows the following algorithm:
 
-1. Check for a `bun.lockb` file in the project root. If it exists, use the version specified in the lockfile.
+1. Check for a `bun.lock` file in the project root. If it exists, use the version specified in the lockfile.
 2. Otherwise, scan up the tree for a `package.json` that includes `"foo"` as a dependency. If found, use the specified semver version or version range.
 3. Otherwise, use `latest`.
 

docs/runtime/bunfig.md

@@ -240,13 +240,13 @@ exact = false
 
 ### `install.saveTextLockfile`
 
-Generate `bun.lock`, a human-readable text-based lockfile. Once generated, Bun will use this file instead of `bun.lockb`, choosing it over the binary lockfile if both are present.
+If false, generate a binary `bun.lockb` instead of a text-based `bun.lock` file when running `bun install` and no lockfile is present.
 
-Default `false`. In Bun v1.2.0 the default lockfile format will change to `bun.lock`.
+Default `true` (since Bun v1.2).
 
 ```toml
 [install]
-saveTextLockfile = true
+saveTextLockfile = false
 ```
 
 <!--
@@ -315,7 +315,7 @@ Valid values are:
 
 ### `install.frozenLockfile`
 
-When true, `bun install` will not update `bun.lockb`. Default `false`. If `package.json` and the existing `bun.lockb` are not in agreement, this will error.
+When true, `bun install` will not update `bun.lock`. Default `false`. If `package.json` and the existing `bun.lock` are not in agreement, this will error.
 
 ```toml
 [install]
@@ -423,7 +423,7 @@ Whether to generate a lockfile on `bun install`. Default `true`.
 save = true
 ```
 
-Whether to generate a non-Bun lockfile alongside `bun.lockb`. (A `bun.lockb` will always be created.) Currently `"yarn"` is the only supported value.
+Whether to generate a non-Bun lockfile alongside `bun.lock`. (A `bun.lock` will always be created.) Currently `"yarn"` is the only supported value.
 
 ```toml
 [install.lockfile]

packages/bun-vscode/README.md

@@ -25,7 +25,7 @@ At its core is the _Bun runtime_, a fast JavaScript runtime designed as a drop-i
 - Test runner codelens
 - Debugger support
 - Run scripts from package.json
-- Visual lockfile viewer (`bun.lockb`)
+- Visual lockfile viewer for old binary lockfiles (`bun.lockb`)
 
 ## In-editor error messages