Inspect the build¶

The help command is used to show available commands and search the help for commands, tasks, or settings. If run without arguments, help lists the available commands.

> help

  help                         Displays this help message or prints detailed help on
                                  requested commands (run 'help <command>').
  about                        Displays basic information about sbt and the build.
  reload                       (Re)loads the project in the current directory
  ...

> help compile

If the argument passed to help is the name of an existing command, setting or task, the help for that entity is displayed. Otherwise, the argument is interpreted as a regular expression that is used to search the help of all commands, settings and tasks.

The tasks command is like help, but operates only on tasks. Similarly, the settings command only operates on settings.

See also help help, help tasks, and help settings.

The tasks command, without arguments, lists the most commonly used tasks. It can take a regular expression to search task names and descriptions. The verbosity can be increased to show or search less commonly used tasks. See help tasks for details.

The settings command, without arguments, lists the most commonly used settings. It can take a regular expression to search setting names and descriptions. The verbosity can be increased to show or search less commonly used settings. See help settings for details.

The inspect command displays several pieces of information about a given setting or task, including the dependencies of a task/setting as well as the tasks/settings that depend on the it. For example,

> inspect test:compile
...
[info] Dependencies:
[info]      test:compile::compile-inputs
[info]      test:compile::streams
[info] Reverse dependencies:
[info]      test:defined-test-names
[info]      test:defined-sbt-plugins
[info]      test:print-warnings
[info]      test:discovered-main-classes
[info]      test:defined-tests
[info]      test:exported-products
[info]      test:products
...

See the Interacting with the Configuration System page for details.

In addition to displaying immediate forward and reverse dependencies as described in the previous section, the inspect command can display the full dependency tree for a task or setting. For example,

> inspect tree clean
[info] *:clean = Task[Unit]
[info]   +-*:clean-files = List(<project>/lib_managed, <project>/target)
[info]   | +-{.}/*:managed-directory = lib_managed
[info]   | +-*:target = target
[info]   |   +-*:base-directory = <project>
[info]   |     +-*:this-project = Project(id: demo, base: <project>, ...
[info]   |
[info]   +-*:clean-keep-files = List(<project>/target/.history)
[info]     +-*:history = Some(<project>/target/.history)
...

For each task, inspect tree show the type of the value generated by the task. For a setting, the toString of the setting is displayed. See the Interacting with the Configuration System page for details on the inspect command.

While the help, settings, and tasks commands display a description of a task, the inspect command also shows the type of a setting or task and the value of a setting. For example:

> inspect update
[info] Task: sbt.UpdateReport
[info] Description:
[info]      Resolves and optionally retrieves dependencies, producing a report.
...

> inspect scala-version
[info] Setting: java.lang.String = 2.9.2
[info] Description:
[info]      The version of Scala used for building.
...

See the Interacting with the Configuration System page for details.

See the Interacting with the Configuration System page for details.

The inspect command can help find scopes where a setting or task is defined. The following example shows that different options may be specified to the Scala for testing and API documentation generation.

> inspect scalac-options
...
[info] Related:
[info]      compile:doc::scalac-options
[info]      test:scalac-options
[info]      */*:scalac-options
[info]      test:doc::scalac-options

See the Interacting with the Configuration System page for details.

The projects command displays the currently loaded projects. The projects are grouped by their enclosing build and the current project is indicated by an asterisk. For example,

> projects
[info] In file:/home/user/demo/
[info]       * parent
[info]         sub
[info] In file:/home/user/dep/
[info]         sample

session list displays the settings that have been added at the command line for the current project. For example,

> session list
  1. maxErrors := 5
  2. scalacOptions += "-explaintypes"

session list-all displays the settings added for all projects. For details, see help session.

> about
[info] This is sbt 0.12.0
[info] The current project is {file:~/code/sbt.github.com/}default
[info] The current project is built against Scala 2.9.2
[info] Available Plugins: com.jsuereth.ghpages.GhPages, com.jsuereth.git.GitPlugin, com.jsuereth.sbtsite.SitePlugin
[info] sbt, sbt plugins, and build definitions are using Scala 2.9.2

The inspect command shows the value of a setting as part of its output, but the show command is dedicated to this job. It shows the output of the setting provided as an argument. For example,

> show organization
[info] com.github.sbt

The show command also works for tasks, described next.

> show update
... <output of update> ...
[info] Update report:
[info]      Resolve time: 122 ms, Download time: 5 ms, Download size: 0 bytes
[info]      compile:
[info]              org.scala-lang:scala-library:2.9.2: ...

The show command will execute the task provided as an argument and then print the result. Note that this is different from the behavior of the inspect command (described in other sections), which does not execute a task and thus can only display its type and not its generated value.

> show compile:dependency-classpath
...
[info] ArrayBuffer(Attributed(~/.sbt/0.12.0/boot/scala-2.9.2/lib/scala-library.jar))

For the test classpath,

> show test:dependency-classpath
...
[info] ArrayBuffer(Attributed(~/code/sbt.github.com/target/scala-2.9.2/classes), Attributed(~/.sbt/0.12.0/boot/scala-2.9.2/lib/scala-library.jar), Attributed(~/.ivy2/cache/junit/junit/jars/junit-4.8.2.jar))

sbt detects the classes with public, static main methods for use by the run method and to tab-complete the run-main method. The discovered-main-classes task does this discovery and provides as its result the list of class names. For example, the following shows the main classes discovered in the main sources:

> show compile:discovered-main-classes
... <runs compile if out of date> ...
[info] List(org.example.Main)

sbt detects tests according to fingerprints provided by test frameworks. The defined-test-names task provides as its result the list of test names detected in this way. For example,

> show test:defined-test-names
... < runs test:compile if out of date > ...
[info] List(org.example.TestA, org.example.TestB)