docs

docs/cli/bun-install.md

@@ -47,6 +47,9 @@ registry = "https://registry.yarnpkg.com/"
 # Install for production? This is the equivalent to the "--production" CLI argument
 production = false
 
+# Save a text-based lockfile? This is equivalent to "--save-text-lockfile" CLI argument
+saveTextLockfile = false
+
 # Disallow changes to lockfile? This is the equivalent to the "--frozen-lockfile" CLI argument
 frozenLockfile = false
 
@@ -108,6 +111,7 @@ export interface Install {
   scopes: Scopes;
   registry: Registry;
   production: boolean;
+  saveTextLockfile: boolean;
   frozenLockfile: boolean;
   dryRun: boolean;
   optional: boolean;

docs/cli/install.md

@@ -174,6 +174,9 @@ peer = true
 # equivalent to `--production` flag
 production = false
 
+# equivalent to `--save-text-lockfile` flag
+saveTextLockfile = false
+
 # equivalent to `--frozen-lockfile` flag
 frozenLockfile = false
 

docs/install/index.md

@@ -86,6 +86,9 @@ peer = true
 # equivalent to `--production` flag
 production = false
 
+# equivalent to `--save-text-lockfile` flag
+saveTextLockfile = false
+
 # equivalent to `--frozen-lockfile` flag
 frozenLockfile = false
 

docs/install/lockfile.md

@@ -72,6 +72,24 @@ $ bun install --yarn
 print = "yarn"
 ```
 
+### 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 choosen over `bun.lockb`.
+
+Bun v1.2.0 will switch the default lockfile format to `bun.lock`.
+
 {% /codetabs %}
 
 {% details summary="Configuring lockfile" %}

docs/runtime/bunfig.md

@@ -238,6 +238,17 @@ By default Bun uses caret ranges; if the `latest` version of a package is `2.4.1
 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.
+
+Default `false`. In Bun v1.2.0 the default lockfile format will change to `bun.lock`.
+
+```toml
+[install]
+saveTextLockfile = true
+```
+
 <!--
 ### `install.prefer`