// Copyright 2017 the original author or authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

[appendix]
[[gradle_command_line]]
== Gradle Command Line

The `gradle` command has the following usage:

----
gradle [option...] [task...]
----

The command-line options available for the `gradle` command are listed below:

`-?`, `-h`, `--help`::
Shows a help message.
`-a`, `--no-rebuild` (deprecated)::
Do not rebuild project dependencies.
`--all`::
Shows additional detail in the task listing. See <<sec:listing_tasks>>.
`-b`, `--build-file`::
Specifies the build file. See <<sec:selecting_build>>.
`--build-cache (incubating)`::
Enables the Gradle build cache. Gradle will try to reuse outputs from previous builds.
`--no-build-cache (incubating)`::
Disables the Gradle build cache.
`-c`, `--settings-file`::
Specifies the settings file.
`--console`::
Specifies which type of console output to generate.
+
Set to `plain` to generate plain text only. This option disables all color and other rich output in the console output.
+
Set to `auto` (the default) to enable color and other rich output in the console output when the build process is attached to a console, or to generate plain text only when not attached to a console.
+
Set to `rich` to enable color and other rich output in the console output, regardless of whether the build process is not attached to a console. When not attached to a console, the build output will use ANSI control characters to generate the rich output.
+
Set to `verbose` to enable color and other rich output like the `rich`, but output more detailed message (task name, output, etc.)
`--continue`::
Continues task execution after a task failure.
`--configure-on-demand (incubating)`::
Only relevant projects are configured in this build run. This means faster builds for large multi-projects. See <<sec:configuration_on_demand>>.
`--no-configure-on-demand (incubating)`::
Disables the use of configuration on demand.
`-D`, `--system-prop`::
Sets a system property of the JVM, for example `-Dmyprop=myvalue`. See <<sec:gradle_properties_and_system_properties>>.
`-d`, `--debug`::
Log in debug mode (includes normal stacktrace). See <<logging>>.
`-g`, `--gradle-user-home`::
Specifies the Gradle user home directory. The default is the `.gradle` directory in the user's home directory.
`--include-build`::
Run the build as a composite, including the specified build. See <<composite_builds>>.
`-I`, `--init-script`::
Specifies an initialization script. See <<init_scripts>>.
`-i`, `--info`::
Set log level to info. See <<logging>>.
`-m`, `--dry-run`::
Runs the build with all task actions disabled. See <<sec:dry_run>>.
`--offline`::
Specifies that the build should operate without accessing network resources. See <<sec:cache_command_line_options>>.
`-P`, `--project-prop`::
Sets a project property of the root project, for example `-Pmyprop=myvalue`. See <<sec:gradle_properties_and_system_properties>>.
`-p`, `--project-dir`::
Specifies the start directory for Gradle. Defaults to current directory. See <<sec:selecting_build>>.
`--parallel (incubating)`::
Build projects in parallel. Gradle will attempt to determine the optimal number of executor threads to use. This option should only be used with decoupled projects (see <<sec:decoupled_projects>>). For limitations of this option please see <<sec:parallel_execution>>.
`--no-parallel (incubating)`::
Disables parallel execution to build projects.
`--max-workers (incubating)`::
Sets the maximum number of workers that Gradle may use. For example `--max-workers=3`. The default is the number of processors.
`--profile`::
Profiles build execution time and generates a report in the `__buildDir__/reports/profile` directory. See <<sec:profiling_build>>.
`--project-cache-dir`::
Specifies the project-specific cache directory. Default value is `.gradle` in the root project directory.
`-q`, `--quiet`::
Log errors only. See <<logging>>.
`--recompile-scripts` (deprecated)::
Forces scripts to be recompiled, bypassing caching. This option has been deprecated and is scheduled to be removed Gradle 5.0. You should avoid using it.
`--refresh-dependencies`::
Refresh the state of dependencies. See <<sec:cache_command_line_options>>.
`--rerun-tasks`::
Specifies that any task optimization is ignored.
`-S`, `--full-stacktrace`::
Print out the full (very verbose) stacktrace for any exceptions. See <<logging>>.
`-s`, `--stacktrace`::
Print out the stacktrace also for user exceptions (e.g. compile error). See <<logging>>.
`--scan (incubating)`::
Creates a build scan. Gradle will auto-apply the build scan plugin with a compatible version. For more information about build scans, please visit https://gradle.com/build-scans[https://gradle.com/build-scans].
`--no-scan (incubating)`::
Disables the creation of a build scan. For more information about build scans, please visit https://gradle.com/build-scans[https://gradle.com/build-scans].
`-t`, `--continuous (incubating)`::
Enables <<continuous_build,continuous building>> - Gradle will automatically re-run when changes are detected.
`-u`, `--no-search-upward`::
Don't search in parent directories for a `settings.gradle` file.
`-v`, `--version`::
Prints version info.
`-w`, `--warn`::
Set log level to warn. See <<logging>>
`-x`, `--exclude-task`::
Specifies a task to be excluded from execution. See <<sec:excluding_tasks_from_the_command_line>>.

The above information is printed to the console when you execute `gradle -h`.

[[daemon_cli]]
=== Daemon command-line options

The <<gradle_daemon>> contains more information about the daemon. For example it includes information how to turn on the daemon by default so that you can avoid using `--daemon` all the time.

`--daemon`::
Uses the Gradle daemon to run the build. Starts the daemon if not running or existing daemon busy. <<gradle_daemon>> contains more detailed information when new daemon processes are started.
`--no-daemon`::
Does not use the Gradle daemon to run the build.
`--foreground`::
Starts the Gradle daemon in the foreground. Useful for debugging or troubleshooting because you can easily monitor the build execution.
`--no-daemon`::
Do not use the Gradle daemon to run the build. Useful occasionally if you have configured Gradle to always run with the daemon by default.
`--status`::
List running and recently stopped Gradle daemons. Only displays daemons of the same Gradle version.
`--stop`::
Stops the Gradle daemon if it is running. You can only stop daemons that were started with the Gradle version you use when running `--stop`.

[[sec:cli_system_properties]]
=== System properties

The following system properties are available for the `gradle` command. Note that command-line options take precedence over system properties.

`gradle.user.home`::
   Specifies the Gradle user home directory.

The <<sec:gradle_configuration_properties>> contains specific information about Gradle configuration available via system properties.

[[sec:cli_environment_variables]]
=== Environment variables

The following environment variables are available for the `gradle` command. Note that command-line options and system properties take precedence over environment variables.

`GRADLE_OPTS`::
Specifies command-line arguments to use to start the JVM. This can be useful for setting the system properties to use for running Gradle. For example you could set `GRADLE_OPTS="-Dorg.gradle.daemon=true"` to use the Gradle daemon without needing to use the `--daemon` option every time you run Gradle. <<sec:gradle_configuration_properties>> contains more information about ways of configuring the daemon without using environmental variables, e.g. in more maintainable and explicit way.
`GRADLE_USER_HOME`::
Specifies the Gradle user home directory (which defaults to “`USER_HOME/.gradle`” if not set).
`JAVA_HOME`::
Specifies the JDK installation directory to use.
