You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2013/11/25 21:20:29 UTC
svn commit: r1545391 -
/karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf
Author: jbonofre
Date: Mon Nov 25 20:20:28 2013
New Revision: 1545391
URL: http://svn.apache.org/r1545391
Log:
[KARAF-2496] Add documentation about subshell and completion mode
Modified:
karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf
Modified: karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf?rev=1545391&r1=1545390&r2=1545391&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/using-console.conf Mon Nov 25 20:20:28 2013
@@ -2,54 +2,309 @@ h1. Using the console
h2. Viewing available commands
-To see a list of the available commands in the console enter
+To see a list of the available commands in the console, you can use the {{help}}:
+
+{code}
+karaf@root()> help
+COMMANDS
+bundle
+bundle:capabilities Displays OSGi capabilities of a given bundles.
+bundle:classes Displays a list of classes contained in the bundle
+...
+{code}
+
+You have the list of all commands with a short description.
+
+You can use the tab key to get a quick list of all commands:
+
{code}
-help
+karaf@root()> Display all 280 possibilities? (y or n)
+...
{code}
-This will show the list of all karaf commands together with a short description.
+h2. Subshell and completion mode
-The list of all karaf commands and their usage is also available in the [Commands section|/commands/commands].
+The commands have a scope and a name. For instance, the command {{feature:list}} has {{feature}} as scope, and {{list}} as name.
-h2. Tab completion
+Karaf "groups" the commands by scope. Each scope form a subshell.
-The Karaf shell offers Tab completion at almost any place in the shell. So another way to see all commands is to {{<tab>}} key at the empty prompt.
+You can directly execute a command with its full qualified name (scope:name):
{code}
-karaf@root> Display all 208 possibilities? (y or n)
-add-role add-url add-user addbundle
-addfilter addregion append-property bundle:capabilities
-bundle:headers bundle:info bundle:install bundle:list bundle:refresh
+karaf@root()> feature:list
...
-karaf@root>
{code}
-The {{<tab>}} key toggles autocompletion anywhere on the line, so if you want to see the commands in the {{osgi}} group, type the first letters and hit {{<tab>}}.
-Depending on the commands, autocompletion may be available for options and arguments too.
+or enter in a subshell and type the command contextual to the subshell:
+
+{code}
+karaf@root()> feature
+karaf@root(feature)> list
+{code}
+
+You can note that you enter in a subshell directly by typing the subshell name (here {{feature}}). You can "switch" directly from a subshell to another:
+
+{code}
+karaf@root()> feature
+karaf@root(feature)> bundle
+karaf@root(bundle)>
+{code}
+
+The prompt displays the current subshell between ().
+
+The {{exit}} command goes to the parent subshell:
+
+{code}
+karaf@root()> feature
+karaf@root(feature)> exit
+karaf@root()>
+{code}
+
+The completion mode defines the behaviour of the tab key and the help command.
+
+You have three different modes available:
+
+* GLOBAL
+* FIRST
+* SUBSHELL
+
+You can define your default completion mode using the completionMode property in {{etc/org.apache.karaf.shell.cfg}} file. By default, you have:
+
+{code}
+completionMode = GLOBAL
+{code}
+
+You can also change the completion mode âon the flyâ (while using the Karaf shell console) using the {{shell:completion}} command:
+
+{code}
+karaf@root()> shell:completion
+GLOBAL
+karaf@root()> shell:completion FIRST
+karaf@root()> shell:completion
+FIRST
+{code}
+
+{{shell:completion}} can inform you about the current completion mode used. You can also provide the new completion mode that you want.
+
+GLOBAL completion mode is the default one in Karaf 3.0.0 (mostly for transition purpose).
+
+GLOBAL mode doesnât really use subshell: itâs the same behavior as in previous Karaf versions.
+
+When you type the tab key, whatever in which subshell you are, the completion will display all commands and all aliases:
+
+{code}
+karaf@root()> <TAB>
+karaf@root()> Display all 273 possibilities? (y or n)
+...
+karaf@root()> feature
+karaf@root(feature)> <TAB>
+karaf@root(feature)> Display all 273 possibilities? (y or n)
+{code}
+
+FIRST completion mode is an alternative to the GLOBAL completion mode.
+
+If you type the tab key on the root level subshell, the completion will display the commands and the aliases from all subshells (as in GLOBAL mode).
+However, if you type the tab key when you are in a subshell, the completion will display only the commands of the current subshell:
+
+{code}
+karaf@root()> shell:completion FIRST
+karaf@root()> <TAB>
+karaf@root()> Display all 273 possibilities? (y or n)
+...
+karaf@root()> feature
+karaf@root(feature)> <TAB>
+karaf@root(feature)>
+info install list repo-add repo-list repo-remove uninstall version-list
+karaf@root(feature)> exit
+karaf@root()> log
+karaf@root(log)> <TAB>
+karaf@root(log)>
+clear display exception-display get log set tail
+{code}
+
+SUBSHELL completion mode is the real subshell mode.
+
+If you type the tab key on the root level, the completion displays the subshell commands (to go into a subshell), and the global aliases.
+Once you are in a subshell, if you type the TAB key, the completion displays the commands of the current subshell:
+
+{code}
+karaf@root()> shell:completion SUBSHELL
+karaf@root()> <TAB>
+karaf@root()>
+* bundle cl config dev feature help instance jaas kar la ld lde log log:list man package region service shell ssh system
+karaf@root()> bundle
+karaf@root(bundle)> <TAB>
+karaf@root(bundle)>
+capabilities classes diag dynamic-import find-class headers info install list refresh requirements resolve restart services start start-level stop
+uninstall update watch
+karaf@root(bundle)> exit
+karaf@root()> camel
+karaf@root(camel)> <TAB>
+karaf@root(camel)>
+backlog-tracer-dump backlog-tracer-info backlog-tracer-start backlog-tracer-stop context-info context-list context-start context-stop endpoint-list route-info route-list route-profile route-reset-stats
+route-resume route-show route-start route-stop route-suspend
+{code}
+
+h2. Unix like environment
+
+Karaf console provides a full Unix like environment.
+
+h3. Help or man
+
+We already saw the usage of the {{help}} command to display all commands available.
+
+But you can also use the {{help}} command to get details about a command:
+
+{code}
+karaf@root()> help feature:list
+DESCRIPTION
+ feature:list
+
+ Lists all existing features available from the defined repositories.
+
+SYNTAX
+ feature:list [options]
-h2. Getting help for a command
+OPTIONS
+ -o, --ordered
+ Display a list using alphabetical order
+ --help
+ Display this help message
+ -i, --installed
+ Display a list of all installed features only
+
+{code}
-To view help on a particular command, type the command followed by {{--help}} or use the {{help}} command followed by the name of the command:
+It's very similar to the {{man}} command on Unix. You can also use the {{man}} command (which is an lias to the {{help}} command):
{code}
-karaf@root> features:list --help
+karaf@root()> man feature:list
DESCRIPTION
- features:list
+ feature:list
Lists all existing features available from the defined repositories.
SYNTAX
- features:list [options]
+ feature:list [options]
OPTIONS
+ -o, --ordered
+ Display a list using alphabetical order
--help
- Display this help message
+ Display this help message
-i, --installed
- Display a list of all installed features only
+ Display a list of all installed features only
{code}
-h2. More...
+You can also use another form to get the command help, by using the {{--help}} option to the command:
+
+{code}
+karaf@root()> feature:list --help
+DESCRIPTION
+ feature:list
+
+ Lists all existing features available from the defined repositories.
+
+SYNTAX
+ feature:list [options]
+
+OPTIONS
+ -o, --ordered
+ Display a list using alphabetical order
+ --help
+ Display this help message
+ -i, --installed
+ Display a list of all installed features only
+
+{code}
-You'll find a more in-depth guide to the shell syntax in the [developers guide|/developers-guide/shell-syntax].
+h3. Completion
+
+When you type the tab key, Karaf tries to complete:
+
+* the subshell
+* the commands
+* the aliases
+* the command arguments
+* the command option
+
+h3. Key binding
+
+Like on most Unix environment, Karaf console support some key bindings:
+
+* the arrows key to navigate in the commands history
+* CTRL-D to logout/shutdown Karaf
+* CTRL-R to search previously executed command
+* CTRL-U to remove the current line
+
+h3. Pipe
+
+You can pipe the output of one command as input to another one. It's a pipe, using the | character:
+
+{code}
+karaf@root()> feature:list|grep -i karaf
+standard | 3.0.0-SNAPSHOT | x | standard-3.0.0-SNAPSHOT | Karaf standard feature
+war | 3.0.0-SNAPSHOT | | standard-3.0.0-SNAPSHOT | Turn Karaf as a full WebContainer
+kar | 3.0.0-SNAPSHOT | x | standard-3.0.0-SNAPSHOT | Provide KAR (KARaf archive) support
+webconsole | 3.0.0-SNAPSHOT | | standard-3.0.0-SNAPSHOT | Base support of the Karaf WebConsole
+ssh | 3.0.0-SNAPSHOT | x | standard-3.0.0-SNAPSHOT | Provide a SSHd server on Karaf
+scheduler | 3.0.0-SNAPSHOT | | standard-3.0.0-SNAPSHOT | Provide a scheduler service in Karaf to fire event
+jasypt-encryption | 3.0.0-SNAPSHOT | | standard-3.0.0-SNAPSHOT | Advanced encryption support for Karaf security
+{code}
+
+h3. Grep, more, find, ...
+
+Karaf console provides some core commands similar to Unix environment:
+
+* {{shell:head}} displays the first line of the input
+* {{shell:source}} executes commands contained in a script
+* {{shell:alias}} creates an alias to an existing command
+* {{shell:history}} prints the commands history
+* {{shell:cat}} displays the content of a file or URL
+* {{shell:if}} allows you to use conditions (if, then, else blocks) in script
+* {{shell:tac}} captures stdin and returns it as a string
+* {{shell:clear}} clears the current console display
+* {{shell:info}} prints various information about the current Karaf instance
+* {{shell:tail}} displays the last lines of the input
+* {{shell:completion}} displays or change the current completion mode
+* {{shell:java}} executes a Java application
+* {{shell:threads}} prints the current thread
+* {{shell:date}} displays the current date (optionally using a format)
+* {{shell:watch}} periodically executes a command and refresh the output
+* {{shell:each}} executes a closure on a list of arguments
+* {{shell:more}} is a file pager
+* {{shell:wc}} prints newline, words, and byte counts for each file
+* {{shell:echo}} echoes and prints arguments to stdout
+* {{shell:new}} creates a new Java object
+* {{shell:edit}} calls a text editor on the current file or URL
+* {{shell:printf}} formats and prints arguments
+* {{shell:exec}} executes a system command
+* {{shell:sleep}} sleeps for a bit then wakes up
+* {{shell:grep}} prints lines matching the given pattern
+* {{shell:sort}} writes sorted concatenation of all files to stdout
+
+You don't have to use the full qualified name of the command, you can directly use the command name:
+
+{code}
+karaf@root(shell)> head --help
+DESCRIPTION
+ shell:head
+
+ Displays the first lines of a file.
+
+SYNTAX
+ shell:head [options] [paths or urls]
+
+ARGUMENTS
+ paths or urls
+ A list of file paths or urls to display separated by whitespaces.
+
+OPTIONS
+ -n
+ The number of lines to display, starting at 1.
+ --help
+ Display this help message
+
+{code}
-The console can also be easily extended by creating new commands as explained in the [developers guide|/developers-guide/extending-console].
+Again, you can find details and all options of these commands using {{help}} command or {{--help}} option.
\ No newline at end of file