From d8ef1f71fbc35d57a8a2cb40494aee5a3aac57c5 Mon Sep 17 00:00:00 2001
From: Armin Ronacher <armin.ronacher@active-4.com>
Date: Sat, 20 Jan 2024 14:40:18 +0100
Subject: [PATCH] Document new lock behavior

---
 docs/guide/pyproject.md | 14 ++++++++++++++
 docs/guide/sources.md   |  2 +-
 docs/guide/sync.md      | 14 ++++++++++++++
 3 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/docs/guide/pyproject.md b/docs/guide/pyproject.md
index 7740bc40f2..581eb9547c 100644
--- a/docs/guide/pyproject.md
+++ b/docs/guide/pyproject.md
@@ -60,6 +60,20 @@ pulled in as indirect dependencies.  These are added here automatically with `ry
 excluded-dependencies = ["cffi"]
 ```
 
+## `tool.rye.lock-with-sources`
+
++++ 0.18.0
+
+When this flag is enabled all `lock` and `sync` operations in the project or workspace
+operate as if `--with-sources` is passed.  This means that all lock files contain the
+full source references.  Note that this can create lock files that contain credentials
+if the sources have credentials included in the URL.
+
+```toml
+[tool.rye]
+lock-with-sources = true
+```
+
 ## `tool.rye.managed`
 
 +++ 0.3.0
diff --git a/docs/guide/sources.md b/docs/guide/sources.md
index 907876ec88..bab56b10f2 100644
--- a/docs/guide/sources.md
+++ b/docs/guide/sources.md
@@ -114,4 +114,4 @@ can be supplied with environment variables.
     [[sources]]
     name = "company-internal"
     url = "https://${INDEX_USERNAME}:${INDEX_PASSWORD}@company.internal/simple/"
-    ```
\ No newline at end of file
+    ```
diff --git a/docs/guide/sync.md b/docs/guide/sync.md
index 3cabdbc9aa..3783451417 100644
--- a/docs/guide/sync.md
+++ b/docs/guide/sync.md
@@ -55,6 +55,20 @@ do want to include those, pass `--pre`
 rye lock Flask --pre
 ```
 
+### `--with-sources`
+
+By default (unless the `tool.rye.lock-with-sources` config key is set to `true` in the
+`pyproject.toml`) lock files are not generated with source references.  This means that
+if custom sources are used the lock file cannot be installed via `pip` unless also
+`--find-links` and other parameters are manually passed.
+
+When this flag is passed then the lock file is generated with references to `--index-url`,
+`--extra-index-url` or `--find-links`.
+
+```
+rye lock --with-sources
+```
+
 ## Sync
 
 Syncing takes the same parameters as `lock` and then some.  Sync will usually first do what