mirror of https://github.com/sbt/sbt.git
210 lines
7.4 KiB
ReStructuredText
210 lines
7.4 KiB
ReStructuredText
=================
|
|
Interactive mode
|
|
=================
|
|
|
|
By default, sbt's interactive mode is started when no commands are provided on the command line or when the `shell` command is invoked.
|
|
|
|
.. howto::
|
|
:id: basic_completion
|
|
:title: Use tab completion
|
|
:type: command
|
|
|
|
testOnly <TAB>
|
|
|
|
As the name suggests, tab completion is invoked by hitting the tab key.
|
|
Suggestions are provided that can complete the text entered to the left of the current cursor position.
|
|
Any part of the suggestion that is unambiguous is automatically appended to the current text.
|
|
Commands typically support tab completion for most of their syntax.
|
|
|
|
As an example, entering `tes` and hitting tab:
|
|
|
|
.. code-block:: console
|
|
|
|
> tes<TAB>
|
|
|
|
results in sbt appending a `t`:
|
|
|
|
.. code-block:: console
|
|
|
|
> test
|
|
|
|
To get further completions, hit tab again:
|
|
|
|
.. code-block:: console
|
|
|
|
> test<TAB>
|
|
testFrameworks testListeners testLoader testOnly testOptions test:
|
|
|
|
Now, there is more than one possibility for the next character, so sbt prints the available options.
|
|
We will select `testOnly` and get more suggestions by entering the rest of the command and hitting tab twice:
|
|
|
|
.. code-block:: console
|
|
|
|
> testOnly<TAB><TAB>
|
|
-- sbt.DagSpecification sbt.EmptyRelationTest sbt.KeyTest sbt.RelationTest sbt.SettingsTest
|
|
|
|
The first tab inserts an unambiguous space and the second suggests names of tests to run.
|
|
The suggestion of `--` is for the separator between test names and options provided to the test framework.
|
|
The other suggestions are names of test classes for one of sbt's modules.
|
|
Test name suggestions require tests to be compiled first.
|
|
If tests have been added, renamed, or removed since the last test compilation, the completions will be out of date until another successful compile.
|
|
|
|
|
|
.. howto::
|
|
:id: verbose_completion
|
|
:title: Show more tab completion suggestions
|
|
:type: text
|
|
|
|
Press tab multiple times.
|
|
|
|
Some commands have different levels of completion. Hitting tab multiple times increases the verbosity of completions. (Presently, this feature is only used by the `set` command.)
|
|
|
|
.. howto::
|
|
:id: show_keybindings
|
|
:title: Show JLine keybindings
|
|
:type: commands
|
|
|
|
> consoleQuick
|
|
scala> :keybindings
|
|
|
|
Both the Scala and sbt command prompts use JLine for interaction. The Scala REPL contains a `:keybindings` command to show many of the keybindings used for JLine. For sbt, this can be used by running one of the :key:`console` commands (:key:`console`, :key:`consoleQuick`, or :key:`consoleProject`) and then running `:keybindings`. For example:
|
|
|
|
.. code-block:: console
|
|
|
|
> consoleProject
|
|
[info] Starting scala interpreter...
|
|
...
|
|
scala> :keybindings
|
|
Reading jline properties for default key bindings.
|
|
Accuracy not guaranteed: treat this as a guideline only.
|
|
|
|
1 CTRL-A: move to the beginning of the line
|
|
2 CTRL-B: move to the previous character
|
|
...
|
|
|
|
|
|
.. howto::
|
|
:id: change_keybindings
|
|
:title: Modify the default JLine keybindings
|
|
|
|
JLine, used by both Scala and sbt, uses a configuration file for many of its keybindings.
|
|
The location of this file can be changed with the system property `jline.keybindings`.
|
|
The default keybindings file is included in the sbt launcher and may be used as a starting point for customization.
|
|
|
|
|
|
.. howto::
|
|
:id: prompt
|
|
:title: Configure the prompt string
|
|
:type: setting
|
|
|
|
shellPrompt := { (s: State) => System.getProperty("user.name") + "> " }
|
|
|
|
By default, sbt only displays `>` to prompt for a command.
|
|
This can be changed through the :key:`shellPrompt` setting, which has type `State => String`.
|
|
:doc:`State </Extending/Build-State>` contains all state for sbt and thus provides access to all build information for use in the prompt string.
|
|
|
|
Examples:
|
|
|
|
::
|
|
|
|
// set the prompt (for this build) to include the project id.
|
|
shellPrompt in ThisBuild := { state => Project.extract(state).currentRef.project + "> " }
|
|
|
|
// set the prompt (for the current project) to include the username
|
|
shellPrompt := { state => System.getProperty("user.name") + "> " }
|
|
|
|
|
|
.. howto::
|
|
:id: history
|
|
:title: Use history
|
|
:type: command
|
|
|
|
!
|
|
|
|
Interactive mode remembers history even if you exit sbt and restart it.
|
|
The simplest way to access history is to press the up arrow key to cycle
|
|
through previously entered commands. Use `Ctrl+r` to incrementally
|
|
search history backwards. The following commands are supported:
|
|
|
|
* `!` Show history command help.
|
|
* `!!` Execute the previous command again.
|
|
* `!:` Show all previous commands.
|
|
* `!:n` Show the last n commands.
|
|
* `!n` Execute the command with index `n`, as shown by the `!:` command.
|
|
* `!-n` Execute the nth command before this one.
|
|
* `!string` Execute the most recent command starting with 'string'
|
|
* `!?string` Execute the most recent command containing 'string'
|
|
|
|
.. howto::
|
|
:id: history_file
|
|
:title: Change the location of the interactive history file
|
|
:type: setting
|
|
|
|
historyPath := Some( baseDirectory.value / ".history" )
|
|
|
|
By default, interactive history is stored in the `target/` directory for the current project (but is not removed by a `clean`).
|
|
History is thus separate for each subproject.
|
|
The location can be changed with the :key:`historyPath` setting, which has type `Option[File]`.
|
|
For example, history can be stored in the root directory for the project instead of the output directory:
|
|
|
|
::
|
|
|
|
historyPath := Some(baseDirectory.value / ".history")
|
|
|
|
The history path needs to be set for each project, since sbt will use the value of :key:`historyPath` for the current project (as selected by the `project` command).
|
|
|
|
|
|
.. howto::
|
|
:id: share_history
|
|
:title: Use the same history for all projects
|
|
:type: setting
|
|
|
|
historyPath := Some( (target in LocalRootProject).value / ".history" )
|
|
|
|
The previous section describes how to configure the location of the history file.
|
|
This setting can be used to share the interactive history among all projects in a build instead of using a different history for each project.
|
|
The way this is done is to set :key:`historyPath` to be the same file, such as a file in the root project's `target/` directory:
|
|
|
|
::
|
|
|
|
historyPath :=
|
|
Some( (target in LocalRootProject).value / ".history")
|
|
|
|
The `in LocalRootProject` part means to get the output directory for the root project for the build.
|
|
|
|
.. howto::
|
|
:id: disable_history
|
|
:title: Disable interactive history
|
|
:type: setting
|
|
|
|
historyPath := None
|
|
|
|
If, for whatever reason, you want to disable history, set :key:`historyPath` to `None` in each project it should be disabled in:
|
|
|
|
historyPath := None
|
|
|
|
.. howto::
|
|
:id: pre_commands
|
|
:title: Run commands before entering interactive mode
|
|
:type: batch
|
|
|
|
clean compile shell
|
|
|
|
Interactive mode is implemented by the `shell` command.
|
|
By default, the `shell` command is run if no commands are provided to sbt on the command line.
|
|
To run commands before entering interactive mode, specify them on the command line followed by `shell`.
|
|
For example,
|
|
|
|
.. code-block:: console
|
|
|
|
$ sbt clean compile shell
|
|
|
|
This runs :key:`clean` and then :key:`compile` before entering the interactive prompt.
|
|
If either :key:`clean` or :key:`compile` fails, sbt will exit without going to the prompt.
|
|
To enter the prompt whether or not these initial commands succeed, prepend `-shell`, which means to run `shell` if any command fails.
|
|
For example,
|
|
|
|
.. code-block:: console
|
|
|
|
$ sbt -shell clean compile shell
|