rust-lang · rust-bors · Apr 16, 2026 · Apr 15, 2026
diff --git a/compiler/rustc_session/src/config.rs b/compiler/rustc_session/src/config.rs
@@ -1320,7 +1320,8 @@ impl OutputFilenames {
     }
 }
 
-pub(crate) fn parse_remap_path_scope(
+// pub for rustdoc
+pub fn parse_remap_path_scope(
     early_dcx: &EarlyDiagCtxt,
     matches: &getopts::Matches,
     unstable_opts: &UnstableOptions,

diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md
@@ -759,6 +759,12 @@ it permits remapping source path prefixes in all output, including compiler diag
 debug information, macro expansions, etc. It takes a value of the form `FROM=TO`
 where a path prefix equal to `FROM` is rewritten to the value `TO`.
 
+## `--remap-path-scope`: Scopes to which the source remapping should be done
+
+This flag is the equivalent flag from `rustc` `--remap-path-scope`.
+
+Defines which scopes of paths should be remapped by --remap-path-prefix.
+
 ### `documentation` scope
 
 `rustdoc` (and by extension `rustc`) have a special `documentation` remapping scope, it

diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs
@@ -15,8 +15,8 @@ use rustc_session::config::{
 use rustc_session::lint::Level;
 use rustc_session::search_paths::SearchPath;
 use rustc_session::{EarlyDiagCtxt, getopts};
-use rustc_span::FileName;
 use rustc_span::edition::Edition;
+use rustc_span::{FileName, RemapPathScopeComponents};
 use rustc_target::spec::TargetTuple;
 
 use crate::core::new_dcx;
@@ -140,6 +140,8 @@ pub(crate) struct Options {
     pub(crate) no_run: bool,
     /// What sources are being mapped.
     pub(crate) remap_path_prefix: Vec<(PathBuf, PathBuf)>,
+    /// Which scope(s) to use with `--remap-path-prefix`
+    pub(crate) remap_path_scope: RemapPathScopeComponents,
 
     /// The path to a rustc-like binary to build tests with. If not set, we
     /// default to loading from `$sysroot/bin/rustc`.
@@ -222,6 +224,7 @@ impl fmt::Debug for Options {
             .field("no_run", &self.no_run)
             .field("test_builder_wrappers", &self.test_builder_wrappers)
             .field("remap-file-prefix", &self.remap_path_prefix)
+            .field("remap-file-scope", &self.remap_path_scope)
             .field("no_capture", &self.no_capture)
             .field("scrape_examples_options", &self.scrape_examples_options)
             .field("unstable_features", &self.unstable_features)
@@ -423,6 +426,8 @@ impl Options {
                 early_dcx.early_fatal(err);
             }
         };
+        let remap_path_scope =
+            rustc_session::config::parse_remap_path_scope(early_dcx, matches, &unstable_opts);
 
         let dcx = new_dcx(error_format, None, diagnostic_width, &unstable_opts);
         let dcx = dcx.handle();
@@ -889,6 +894,7 @@ impl Options {
             no_run,
             test_builder_wrappers,
             remap_path_prefix,
+            remap_path_scope,
             no_capture,
             crate_name,
             output_format,

diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs
@@ -211,6 +211,7 @@ pub(crate) fn create_config(
         lint_cap,
         scrape_examples_options,
         remap_path_prefix,
+        remap_path_scope,
         target_modifiers,
         ..
     }: RustdocOptions,
@@ -270,6 +271,7 @@ pub(crate) fn create_config(
         crate_name,
         test,
         remap_path_prefix,
+        remap_path_scope,
         output_types: if let Some(file) = render_options.dep_info() {
             OutputTypes::new(&[(OutputType::DepInfo, file.cloned())])
         } else {

diff --git a/src/librustdoc/doctest.rs b/src/librustdoc/doctest.rs
@@ -171,6 +171,7 @@ pub(crate) fn run(dcx: DiagCtxtHandle<'_>, input: Input, options: RustdocOptions
         target_triple: options.target.clone(),
         crate_name: options.crate_name.clone(),
         remap_path_prefix: options.remap_path_prefix.clone(),
+        remap_path_scope: options.remap_path_scope.clone(),
         unstable_opts: options.unstable_opts.clone(),
         error_format: options.error_format.clone(),
         target_modifiers: options.target_modifiers.clone(),

diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs
@@ -556,6 +556,14 @@ fn opts() -> Vec<RustcOptGroup> {
             "Remap source names in compiler messages",
             "FROM=TO",
         ),
+        opt(
+            Unstable,
+            Opt,
+            "",
+            "remap-path-scope",
+            "Defines which scopes of paths should be remapped by `--remap-path-prefix`",
+            "[macro,diagnostics,debuginfo,coverage,object,all]",
+        ),
         opt(
             Unstable,
             FlagMulti,

diff --git a/tests/run-make/rustdoc-default-output/output-default.stdout b/tests/run-make/rustdoc-default-output/output-default.stdout
@@ -160,6 +160,9 @@ Options:
                         rustdoc will emit a hard error.
         --remap-path-prefix FROM=TO
                         Remap source names in compiler messages
+        --remap-path-scope [macro,diagnostics,debuginfo,coverage,object,all]
+                        Defines which scopes of paths should be remapped by
+                        `--remap-path-prefix`
         --show-type-layout 
                         Include the memory layout of types in the docs
         --no-capture    Don't capture stdout and stderr of tests

diff --git a/tests/rustdoc-ui/remap-path-prefix-doctest.rs b/tests/rustdoc-ui/remap-path-prefix-doctest.rs
@@ -0,0 +1,22 @@
+// This test checks the output of remapping with `--remap-path-prefix` and
+// `--remap-path-scope` with a doctest.
+
+//@ failure-status: 101
+//@ rustc-env:RUST_BACKTRACE=0
+//@ normalize-stdout: "finished in \d+\.\d+s" -> "finished in $$TIME"
+
+//@ revisions: with-diag-scope with-macro-scope with-object-scope with-doc-scope
+//@ revisions: without-scope
+
+//@ compile-flags:--test --test-args --test-threads=1
+//@ compile-flags:-Z unstable-options --remap-path-prefix={{src-base}}=remapped_path
+
+//@[with-diag-scope] compile-flags: -Zunstable-options --remap-path-scope=diagnostics
+//@[with-macro-scope] compile-flags: -Zunstable-options --remap-path-scope=macro
+//@[with-object-scope] compile-flags: -Zunstable-options --remap-path-scope=debuginfo
+//@[with-doc-scope] compile-flags: -Zunstable-options --remap-path-scope=documentation
+
+/// ```
+/// fn invalid(
+/// ```
+pub struct SomeStruct;
diff --git a/tests/rustdoc-ui/remap-path-prefix-doctest.with-diag-scope.stdout b/tests/rustdoc-ui/remap-path-prefix-doctest.with-diag-scope.stdout
@@ -0,0 +1,24 @@
+
+running 1 test
+test $DIR/remap-path-prefix-doctest.rs - SomeStruct (line 19) ... FAILED
+
+failures:
+
+---- $DIR/remap-path-prefix-doctest.rs - SomeStruct (line 19) stdout ----
+error: this file contains an unclosed delimiter
+  --> $DIR/remap-path-prefix-doctest.rs:20:12
+   |
+LL | fn invalid(
+   |           -^
+   |           |
+   |           unclosed delimiter
+
+error: aborting due to 1 previous error
+
+Couldn't compile the test.
+
+failures:
+    $DIR/remap-path-prefix-doctest.rs - SomeStruct (line 19)
+
+test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
+
diff --git a/tests/rustdoc-ui/remap-path-prefix-doctest.with-doc-scope.stdout b/tests/rustdoc-ui/remap-path-prefix-doctest.with-doc-scope.stdout
@@ -0,0 +1,24 @@
+
+running 1 test
+test remapped_path/remap-path-prefix-doctest.rs - SomeStruct (line 19) ... FAILED
+
+failures:
+
+---- remapped_path/remap-path-prefix-doctest.rs - SomeStruct (line 19) stdout ----
+error: this file contains an unclosed delimiter
+  --> remapped_path/remap-path-prefix-doctest.rs:20:12
+   |
+LL | fn invalid(
+   |           -^
+   |           |
+   |           unclosed delimiter
+
+error: aborting due to 1 previous error
+
+Couldn't compile the test.
+
+failures:
+    remapped_path/remap-path-prefix-doctest.rs - SomeStruct (line 19)
+
+test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
+
diff --git a/tests/rustdoc-ui/remap-path-prefix-doctest.with-macro-scope.stdout b/tests/rustdoc-ui/remap-path-prefix-doctest.with-macro-scope.stdout
@@ -0,0 +1,24 @@
+
+running 1 test
+test $DIR/remap-path-prefix-doctest.rs - SomeStruct (line 19) ... FAILED
+
+failures:
+
+---- $DIR/remap-path-prefix-doctest.rs - SomeStruct (line 19) stdout ----
+error: this file contains an unclosed delimiter
+  --> $DIR/remap-path-prefix-doctest.rs:20:12
+   |
+LL | fn invalid(
+   |           -^
+   |           |
+   |           unclosed delimiter
+
+error: aborting due to 1 previous error
+
+Couldn't compile the test.
+
+failures:
+    $DIR/remap-path-prefix-doctest.rs - SomeStruct (line 19)
+
+test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
+
diff --git a/tests/rustdoc-ui/remap-path-prefix-doctest.with-object-scope.stdout b/tests/rustdoc-ui/remap-path-prefix-doctest.with-object-scope.stdout
@@ -0,0 +1,24 @@
+
+running 1 test
+test $DIR/remap-path-prefix-doctest.rs - SomeStruct (line 19) ... FAILED
+
+failures:
+
+---- $DIR/remap-path-prefix-doctest.rs - SomeStruct (line 19) stdout ----
+error: this file contains an unclosed delimiter
+  --> $DIR/remap-path-prefix-doctest.rs:20:12
+   |
+LL | fn invalid(
+   |           -^
+   |           |
+   |           unclosed delimiter
+
+error: aborting due to 1 previous error
+
+Couldn't compile the test.
+
+failures:
+    $DIR/remap-path-prefix-doctest.rs - SomeStruct (line 19)
+
+test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
+
diff --git a/tests/rustdoc-ui/remap-path-prefix-doctest.without-scope.stdout b/tests/rustdoc-ui/remap-path-prefix-doctest.without-scope.stdout
@@ -0,0 +1,24 @@
+
+running 1 test
+test remapped_path/remap-path-prefix-doctest.rs - SomeStruct (line 19) ... FAILED
+
+failures:
+
+---- remapped_path/remap-path-prefix-doctest.rs - SomeStruct (line 19) stdout ----
+error: this file contains an unclosed delimiter
+  --> remapped_path/remap-path-prefix-doctest.rs:20:12
+   |
+LL | fn invalid(
+   |           -^
+   |           |
+   |           unclosed delimiter
+
+error: aborting due to 1 previous error
+
+Couldn't compile the test.
+
+failures:
+    remapped_path/remap-path-prefix-doctest.rs - SomeStruct (line 19)
+
+test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in $TIME
+
diff --git a/tests/rustdoc-ui/remap-path-prefix-macro.rs → ...tdoc-ui/remap-path-prefix-macro-138520.rs b/tests/rustdoc-ui/remap-path-prefix-macro.rs → ...tdoc-ui/remap-path-prefix-macro-138520.rs
diff --git a/tests/rustdoc-ui/remap-path-prefix.rs b/tests/rustdoc-ui/remap-path-prefix.rs
@@ -0,0 +1,28 @@
+// This test exercises `--remap-path-prefix` and `--remap-path-scope` with macros,
+// like file!() and a diagnostic with compile_error!().
+//
+// See the compiler test suite for a more advanced tests, we just want to
+// make sure here that rustdoc passes the right scopes to the underline rustc APIs.
+
+//@ revisions: with-diag-scope with-macro-scope with-debuginfo-scope with-doc-scope
+//@ revisions: without-scopes without-remap
+
+//@[with-diag-scope] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
+//@[with-macro-scope] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
+//@[with-debuginfo-scope] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
+//@[with-doc-scope] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
+//@[without-scopes] compile-flags: -Zunstable-options --remap-path-prefix={{src-base}}=remapped
+
+//@[with-diag-scope] compile-flags: -Zunstable-options --remap-path-scope=diagnostics
+//@[with-macro-scope] compile-flags: -Zunstable-options --remap-path-scope=macro
+//@[with-debuginfo-scope] compile-flags: -Zunstable-options --remap-path-scope=debuginfo
+//@[with-doc-scope] compile-flags: -Zunstable-options --remap-path-scope=documentation
+
+compile_error!(concat!("file!() = ", file!()));
+//[with-macro-scope]~^ ERROR file!()
+//[with-debuginfo-scope]~^^ ERROR file!()
+//[with-doc-scope]~^^^ ERROR file!()
+//[without-remap]~^^^^ ERROR file!()
+
+//[with-diag-scope]~? ERROR file!()
+//[without-scopes]~? ERROR file!()
diff --git a/tests/rustdoc-ui/remap-path-prefix.with-debuginfo-scope.stderr b/tests/rustdoc-ui/remap-path-prefix.with-debuginfo-scope.stderr
@@ -0,0 +1,8 @@
+error: file!() = $DIR/remap-path-prefix.rs
+  --> $DIR/remap-path-prefix.rs:21:1
+   |
+LL | compile_error!(concat!("file!() = ", file!()));
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+
diff --git a/tests/rustdoc-ui/remap-path-prefix.with-diag-scope.stderr b/tests/rustdoc-ui/remap-path-prefix.with-diag-scope.stderr
@@ -0,0 +1,8 @@
+error: file!() = $DIR/remap-path-prefix.rs
+  --> remapped/remap-path-prefix.rs:21:1
+   |
+LL | compile_error!(concat!("file!() = ", file!()));
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+
diff --git a/tests/rustdoc-ui/remap-path-prefix.with-doc-scope.stderr b/tests/rustdoc-ui/remap-path-prefix.with-doc-scope.stderr
@@ -0,0 +1,8 @@
+error: file!() = $DIR/remap-path-prefix.rs
+  --> $DIR/remap-path-prefix.rs:21:1
+   |
+LL | compile_error!(concat!("file!() = ", file!()));
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+
diff --git a/tests/rustdoc-ui/remap-path-prefix.with-macro-scope.stderr b/tests/rustdoc-ui/remap-path-prefix.with-macro-scope.stderr
@@ -0,0 +1,8 @@
+error: file!() = remapped/remap-path-prefix.rs
+  --> $DIR/remap-path-prefix.rs:21:1
+   |
+LL | compile_error!(concat!("file!() = ", file!()));
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+
diff --git a/tests/rustdoc-ui/remap-path-prefix.without-remap.stderr b/tests/rustdoc-ui/remap-path-prefix.without-remap.stderr
@@ -0,0 +1,8 @@
+error: file!() = $DIR/remap-path-prefix.rs
+  --> $DIR/remap-path-prefix.rs:21:1
+   |
+LL | compile_error!(concat!("file!() = ", file!()));
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+
diff --git a/tests/rustdoc-ui/remap-path-prefix.without-scopes.stderr b/tests/rustdoc-ui/remap-path-prefix.without-scopes.stderr
@@ -0,0 +1,8 @@
+error: file!() = remapped/remap-path-prefix.rs
+  --> remapped/remap-path-prefix.rs:21:1
+   |
+LL | compile_error!(concat!("file!() = ", file!()));
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to 1 previous error
+
diff --git a/tests/rustdoc-ui/remap-path-scope-invalid.foo.stderr b/tests/rustdoc-ui/remap-path-scope-invalid.foo.stderr
@@ -0,0 +1,2 @@
+error: argument for `--remap-path-scope` must be a comma separated list of scopes: `macro`, `diagnostics`, `documentation`, `debuginfo`, `coverage`, `object`, `all`
+
diff --git a/tests/rustdoc-ui/remap-path-scope-invalid.rs b/tests/rustdoc-ui/remap-path-scope-invalid.rs
@@ -0,0 +1,10 @@
+// Error on invalid --remap-path-scope arguments
+
+//@ revisions: foo underscore
+//@ compile-flags: -Zunstable-options
+//@ [foo]compile-flags: --remap-path-scope=foo
+//@ [underscore]compile-flags: --remap-path-scope=macro_object
+
+//~? RAW argument for `--remap-path-scope
+
+fn main() {}
diff --git a/tests/rustdoc-ui/remap-path-scope-invalid.underscore.stderr b/tests/rustdoc-ui/remap-path-scope-invalid.underscore.stderr
@@ -0,0 +1,2 @@
+error: argument for `--remap-path-scope` must be a comma separated list of scopes: `macro`, `diagnostics`, `documentation`, `debuginfo`, `coverage`, `object`, `all`
+
diff --git a/tests/rustdoc-ui/remap-path-scope-unstable.rs b/tests/rustdoc-ui/remap-path-scope-unstable.rs
@@ -0,0 +1,7 @@
+// Regression test to make sure `--remap-path-scope` is unstable in rustdoc
+
+//@ compile-flags:--remap-path-scope macro
+
+//~? RAW the `-Z unstable-options` flag must also be passed to enable the flag `remap-path-scope`
+
+fn main() {}
diff --git a/tests/rustdoc-ui/remap-path-scope-unstable.stderr b/tests/rustdoc-ui/remap-path-scope-unstable.stderr
@@ -0,0 +1,2 @@
+error: the `-Z unstable-options` flag must also be passed to enable the flag `remap-path-scope`
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		error: argument for `--remap-path-scope` must be a comma separated list of scopes: `macro`, `diagnostics`, `documentation`, `debuginfo`, `coverage`, `object`, `all`
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		error: the `-Z unstable-options` flag must also be passed to enable the flag `remap-path-scope`