Merge pull request #23921 Restore --no-rebuild command line option

* Reverts #22992
* Fixes #23888

Co-authored-by: Paul Merlin <paul@gradle.com>

subprojects/core/src/integTest/groovy/org/gradle/api/ConfigurationOnDemandIntegrationTest.groovy

@@ -254,6 +254,7 @@ project(':api') {
         fixture.assertProjectsConfigured(":", ":impl", ":api")
     }
 
+    @ToBeFixedForConfigurationCache(because = "test expects configuration phase")
     def "respects buildProjectDependencies setting"() {
         settingsFile << "include 'api', 'impl', 'other'"
         file("impl/build.gradle") << """
@@ -270,6 +271,15 @@ project(':api') {
         then:
         executed ":api:jar", ":impl:jar"
         fixture.assertProjectsConfigured(":", ":impl", ":api")
+
+        when:
+        run("impl:build", "--no-rebuild") // impl -> api
+
+        then:
+        executed ":impl:jar"
+        notExecuted ":api:jar"
+        // :api is configured to resolve impl.compileClasspath configuration
+        fixture.assertProjectsConfigured(":", ":impl", ":api")
     }
 
     def "respects external task dependencies"() {

subprojects/core/src/main/java/org/gradle/initialization/StartParameterBuildOptions.java

@@ -56,6 +56,7 @@ public class StartParameterBuildOptions extends BuildOptionSet<StartParameterInt
         options.add(new DryRunOption());
         options.add(new ContinuousOption());
         options.add(new ContinuousBuildQuietPeriodOption());
+        options.add(new NoProjectDependenciesRebuildOption());
         options.add(new InitScriptOption());
         options.add(new ExcludeTaskOption());
         options.add(new IncludeBuildOption());
@@ -192,6 +193,20 @@ public void applyTo(int quietPeriodMillis, StartParameterInternal startParameter
         }
     }
 
+    public static class NoProjectDependenciesRebuildOption extends EnabledOnlyBooleanBuildOption<StartParameterInternal> {
+        private static final String LONG_OPTION = "no-rebuild";
+        private static final String SHORT_OPTION = "a";
+
+        public NoProjectDependenciesRebuildOption() {
+            super(null, CommandLineOptionConfiguration.create(LONG_OPTION, SHORT_OPTION, "Do not rebuild project dependencies."));
+        }
+
+        @Override
+        public void applyTo(StartParameterInternal settings, Origin origin) {
+            settings.setBuildProjectDependencies(false);
+        }
+    }
+
     public static class InitScriptOption extends ListBuildOption<StartParameterInternal> {
         public InitScriptOption() {
             super(null, CommandLineOptionConfiguration.create("init-script", "I", "Specify an initialization script."));

subprojects/docs/src/docs/userguide/authoring-builds/organizing_gradle_projects.adoc

@@ -211,6 +211,10 @@ Optionally, the `buildSrc` directory can host a build script if additional confi
 =====
 ====
 
+NOTE: A change in `buildSrc` causes the whole project to become out-of-date.
+Thus, when making small incremental changes, the <<command_line_interface#sec:command_line_execution_options, `--no-rebuild` command-line option>> is often helpful to get faster feedback.
+Remember to run a full build regularly or at least when you're done, though.
+
 == Declare properties in `gradle.properties` file
 
 In Gradle, properties can be defined in the build script, in a `gradle.properties` file or as parameters on the command line.

subprojects/docs/src/docs/userguide/migration/upgrading_version_7.adoc

@@ -93,7 +93,7 @@ test {
 }
 ```
 
-=== Removed APIs and features
+=== Removed APIs
 
 ==== Legacy ArtifactTransform API
 
@@ -113,11 +113,6 @@ The legacy `AntlrSourceVirtualDirectory` API has been removed.
 This change affects the `antlr` plugin.
 In Gradle 8.0 and above, use the `AntlrSourceDirectorySet` source set extension instead.
 
-==== `--no-rebuild` command line option
-
-The `--no-rebuild` command line option and its short variant `-a` have been removed.
-They were used to tell Gradle not to rebuild project dependencies and could lead to wrong results.
-
 ==== JvmPluginsHelper
 
 A deprecated `configureDocumentationVariantWithArtifact` method of the `JvmPluginsHelper` class which did not require a `FileResolver` has been removed.

subprojects/docs/src/docs/userguide/reference/command_line_interface.adoc

@@ -590,6 +590,10 @@ Indicates that versions for the specified modules have to be updated in the lock
 This flag also implies `--write-locks`.
 Learn more about this in <<dependency_locking.adoc#dependency-locking,dependency locking>>.
 
+`-a`, `--no-rebuild`::
+Do not rebuild project dependencies.
+Useful for <<organizing_gradle_projects.adoc#sec:build_sources, debugging and fine-tuning `buildSrc`>>, but can lead to wrong results. Use with caution!
+
 [[sec:dependency_verification_options]]
 == Dependency verification options
 Learn more about this in <<dependency_verification.adoc#verifying-dependencies,dependency verification>>.