# Chapter 11. Using the Gradle Command-Line

This chapter introduces the basics of the Gradle command-line. You run a build using the gradle command, which you have already seen in action in previous chapters.

## 11.1. Executing multiple tasks

You can execute multiple tasks in a single build by listing each of the tasks on the command-line. For example, the command `gradle compile test` will execute the `compile` and `test` tasks. Gradle will execute the tasks in the order that they are listed on the command-line, and will also execute the dependencies for each task. Each task is executed once only, regardless of how it came to be included in the build: whether it was specified on the command-line, or it a dependency of another task, or both. Let's look at an example.

Below four tasks are defined. Both `dist` and `test` depend on the `compile` task. Running `gradle dist test` for this build script results in the `compile` task being executed only once.

Figure 11.1. Task dependencies

Example 11.1. Executing multiple tasks

`build.gradle`

    task compile << {
        println 'compiling source'
    }

    task compileTest(dependsOn: compile) << {
        println 'compiling unit tests'
    }

    task test(dependsOn: [compile, compileTest]) << {
        println 'running unit tests'
    }

    task dist(dependsOn: [compile, test]) << {
        println 'building the distribution'
    }

Output of `gradle dist test`

    > gradle dist test
    :compile
    compiling source
    :compileTest
    compiling unit tests
    :test
    running unit tests
    :dist
    building the distribution

    BUILD SUCCESSFUL

    Total time: 1 secs

Because each task is executed once only, executing `gradle test test` is exactly the same as executing `gradle test`.

## 11.2. Excluding tasks

You can exclude a task from being executed using the `-x` command-line option and providing the name of the task to exclude. Let's try this with the sample build file above.

Example 11.2. Excluding tasks

Output of `gradle dist -x test`

    > gradle dist -x test
    :compile
    compiling source
    :dist
    building the distribution

    BUILD SUCCESSFUL

    Total time: 1 secs

You can see from the output of this example, that the `test` task is not executed, even though it is a dependency of the `dist` task. You will also notice that the `test` task's dependencies, such as `compileTest` are not executed either. Those dependencies of `test` that are required by another task, such as `compile`, are still executed.

## 11.3. Task name abbreviation

When you specify tasks on the command-line, you don't have to provide the full name of the task. You only need to provide enough of the task name to uniquely identify the task. For example, in the sample build above, you can execute task `dist` by running `gradle d`:

Example 11.3. Abbreviated task name

Output of `gradle di`

    > gradle di
    :compile
    compiling source
    :compileTest
    compiling unit tests
    :test
    running unit tests
    :dist
    building the distribution

    BUILD SUCCESSFUL

    Total time: 1 secs

You can also abbreviate each word in a camel case task name. For example, you can execute task `compileTest` by running `gradle compTest` or even `gradle cT`

Example 11.4. Abbreviated camel case task name

Output of `gradle cT`

    > gradle cT
    :compile
    compiling source
    :compileTest
    compiling unit tests

    BUILD SUCCESSFUL

    Total time: 1 secs

You can also use these abbreviations with the `-x` command-line option.

## 11.4. Selecting which build to execute

When you run the gradle command, it looks for a build file in the current directory. You can use the `-b` option to select another build file. If you use `-b` option then `settings.gradle` file is not used. Example:

Example 11.5. Selecting the project using a build file

`subdir/myproject.gradle`

    task hello << {
        println "using build file '$buildFile.name' in '$buildFile.parentFile.name'."
    }

Output of `gradle -q -b subdir/myproject.gradle hello`

    > gradle -q -b subdir/myproject.gradle hello
    using build file 'myproject.gradle' in 'subdir'.

Alternatively, you can use the `-p` option to specify the project directory to use. For multi-project builds you should use `-p` option instead of `-b` option.

Example 11.6. Selecting the project using project directory

Output of `gradle -q -p subdir hello`

    > gradle -q -p subdir hello
    using build file 'build.gradle' in 'subdir'.

## 11.5. Obtaining information about your build

Gradle provides several built-in tasks which show particular details of your build. This can be useful for understanding the structure and dependencies of your build, and for debugging problems.

In addition to the built-in tasks shown below, you can also use the project report plugin to add tasks to your project which will generate these reports.

### 11.5.1. Listing projects

Running `gradle projects` gives you a list of the sub-projects of the selected project, displayed in a hierarchy. Here is an example:

Example 11.7. Obtaining information about projects

Output of `gradle -q projects`

    > gradle -q projects
    ------------------------------------------------------------
    Root project
    ------------------------------------------------------------

    Root project 'projectReports'
    +--- Project ':api' - The shared API for the application
    \--- Project ':webapp' - The Web application implementation

    To see a list of the tasks of a project, run gradle <project-path>:tasks
    For example, try running gradle :api:tasks

The report shows the description of each project, if specified. You can provide a description for a project by setting the `description` property:

Example 11.8. Providing a description for a project

`build.gradle`

    description = 'The shared API for the application'

### 11.5.2. Listing tasks

Running `gradle tasks` gives you a list of the main tasks of the selected project. This report shows the default tasks for the project, if any, and a description for each task. Below is an example of this report:

Example 11.9. Obtaining information about tasks

Output of `gradle -q tasks`

    > gradle -q tasks
    ------------------------------------------------------------
    All tasks runnable from root project
    ------------------------------------------------------------

    Default tasks: dists

    Build tasks
    -----------
    clean - Deletes the build directory (build)
    dists - Builds the distribution
    libs - Builds the JAR

    Help tasks
    ----------
    dependencies - Displays the dependencies of root project 'projectReports'.
    help - Displays a help message
    projects - Displays the sub-projects of root project 'projectReports'.
    properties - Displays the properties of root project 'projectReports'.
    tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).

    To see all tasks and more detail, run with --all.

By default, this report shows only those tasks which have been assigned to a task group. You can do this by setting the `group` property for the task. You can also set the `description` property, to provide a description to be included in the report.

Example 11.10. Changing the content of the task report

`build.gradle`

    dists {
        description = 'Builds the distribution'
        group = 'build'
    }

You can obtain more information in the task listing using the `--all` option. With this option, the task report lists all tasks in the project, grouped by main task, and the dependencies for each task. Here is an example:

Example 11.11. Obtaining more information about tasks

Output of `gradle -q tasks --all`

    > gradle -q tasks --all
    ------------------------------------------------------------
    All tasks runnable from root project
    ------------------------------------------------------------

    Default tasks: dists

    Build tasks
    -----------
    clean - Deletes the build directory (build)
    api:clean - Deletes the build directory (build)
    webapp:clean - Deletes the build directory (build)
    dists - Builds the distribution [api:libs, webapp:libs]
        docs - Builds the documentation
    api:libs - Builds the JAR
        api:compile - Compiles the source files
    webapp:libs - Builds the JAR [api:libs]
        webapp:compile - Compiles the source files

    Help tasks
    ----------
    dependencies - Displays the dependencies of root project 'projectReports'.
    help - Displays a help message
    projects - Displays the sub-projects of root project 'projectReports'.
    properties - Displays the properties of root project 'projectReports'.
    tasks - Displays the tasks runnable from root project 'projectReports' (some of the displayed tasks may belong to subprojects).

### 11.5.3. Listing project dependencies

Running `gradle dependencies` gives you a list of the dependencies of the selected project, broken down by configuration. For each configuration, the direct and transitive dependencies of that configuration are shown in a tree. Below is an example of this report:

Example 11.12. Obtaining information about dependencies

Output of `gradle -q dependencies api:dependencies webapp:dependencies`

    > gradle -q dependencies api:dependencies webapp:dependencies
    ------------------------------------------------------------
    Root project
    ------------------------------------------------------------

    No configurations

    ------------------------------------------------------------
    Project :api - The shared API for the application
    ------------------------------------------------------------

    compile
    \--- org.codehaus.groovy:groovy-all:1.8.4 [default]

    ------------------------------------------------------------
    Project :webapp - The Web application implementation
    ------------------------------------------------------------

    compile
    +--- projectReports:api:1.0-SNAPSHOT [compile]
    |    \--- org.codehaus.groovy:groovy-all:1.8.4 [default]
    \--- commons-io:commons-io:1.2 [default]

### 11.5.4. Listing project properties

Running `gradle properties` gives you a list of the properties of the selected project. This is a snippet from the output:

Example 11.13. Information about properties

Output of `gradle -q api:properties`

    > gradle -q api:properties
    ------------------------------------------------------------
    Project :api - The shared API for the application
    ------------------------------------------------------------

    allprojects: [project ':api']
    ant: org.gradle.api.internal.project.DefaultAntBuilder@12345
    antBuilderFactory: org.gradle.api.internal.project.DefaultAntBuilderFactory@12345
    artifacts: org.gradle.api.internal.artifacts.dsl.DefaultArtifactHandler@12345
    asDynamicObject: org.gradle.api.internal.ExtensibleDynamicObject@12345
    buildDir: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build
    buildFile: /home/user/gradle/samples/userguide/tutorial/projectReports/api/build.gradle

### 11.5.5. Profiling a build

The `--profile` command line option will record some useful timing information while your build is running and write a report to the `build/reports/profile` directory. The report will be named using the time when the build was run.

This report lists summary times and details for both the configuration phase and task execution. The times for configuration and task execution are sorted with the most expensive operations first. The task execution results also indicate if any tasks were skipped (and the reason) or if tasks that were not skipped did no work.

Builds which utilize a buildSrc directory will generate a second profile report for buildSrc in the `buildSrc/build` directory.

## 11.6. Dry Run

Sometimes you are interested in which tasks are executed in which order for a given set of tasks specified on the command line, but you don't want the tasks to be executed. You can use the `-m` option for this. For example `gradle -m clean compile` shows you all tasks to be executed as part of the `clean` and `compile` tasks. This is complementary to the `tasks` task, which shows you the tasks which are available for execution.

## 11.7. Summary

In this chapter, you have seen some of the things you can do with Gradle from the command-line. You can find out more about the gradle command in Appendix C, Gradle Command Line.