diff --git a/sphinx_doc_src/tutorial.rst b/sphinx_doc_src/tutorial.rst index 5a94c2081..73f47a625 100644 --- a/sphinx_doc_src/tutorial.rst +++ b/sphinx_doc_src/tutorial.rst @@ -22,7 +22,7 @@ which means you are all set up and can start using fish:: > fish Welcome to fish, the friendly interactive shell Type help for instructions on how to use fish - you@hostname ~>____ + you@hostname ~> This prompt that you see above is the ``fish`` default prompt: it shows your username, hostname, and working directory. @@ -45,7 +45,7 @@ Running Commands ``fish`` runs commands like other shells: you type a command, followed by its arguments. Spaces are separators:: - >_ echo hello world + > echo hello world hello world @@ -53,9 +53,9 @@ This runs the command `echo` with the arguments `hello` and `world`. You can include a literal space in an argument with a backslash, or by using single or double quotes:: - >_ mkdir My\ Files - >_ cp ~/Some\ File 'My Files' - >_ ls "My Files" + > mkdir My\ Files + > cp ~/Some\ File 'My Files' + > ls "My Files" Some File @@ -71,7 +71,7 @@ Getting Help :: - >_ man set + > man set set - handle shell variables Synopsis... @@ -82,17 +82,17 @@ Syntax Highlighting You'll quickly notice that ``fish`` performs syntax highlighting as you type. Invalid commands are colored red by default:: - >_ /bin/mkd + > /bin/mkd A command may be invalid because it does not exist, or refers to a file that you cannot execute. When the command becomes valid, it is shown in a different color:: - >_ /bin/mkdir + > /bin/mkdir ``fish`` will underline valid file paths as you type them:: - >_ cat ~/somefi___ + > cat ~/somefi This tells you that there exists a file that starts with '``somefi``', which is useful feedback as you type. @@ -105,7 +105,7 @@ Wildcards ``fish`` supports the familiar wildcard ``*``. To list all JPEG files:: - >_ ls *.jpg + > ls *.jpg lena.jpg meena.jpg santa maria.jpg @@ -113,14 +113,14 @@ Wildcards You can include multiple wildcards:: - >_ ls l*.p* + > ls l*.p* lena.png lesson.pdf Especially powerful is the recursive wildcard ** which searches directories recursively:: - >_ ls /var/**.log + > ls /var/**.log /var/log/system.log /var/run/sntp.log @@ -133,8 +133,8 @@ Pipes and Redirections You can pipe between commands with the usual vertical bar:: - >_ echo hello world | wc - 1 2 12 + > echo hello world | wc + 1 2 12 stdin and stdout can be redirected via the familiar `<` and `<`. stderr is redirected with a `2>`. @@ -143,7 +143,7 @@ stdin and stdout can be redirected via the familiar `<` and `<`. stderr is redir :: - >_ grep fish < /etc/shells > ~/output.txt 2> ~/errors.txt + > grep fish < /etc/shells > ~/output.txt 2> ~/errors.txt @@ -152,17 +152,17 @@ Autosuggestions ``fish`` suggests commands as you type, and shows the suggestion to the right of the cursor, in gray. For example:: - >_ /bin/h___ostname + > /bin/hostname It knows about paths and options:: - >_ grep --i___gnore-case + > grep --ignore-case And history too. Type a command once, and you can re-summon it by just typing a few letters:: - >_ r<___sync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo + > rsync -avze ssh . myname@somelonghost.com:/some/long/path/doo/dee/doo/dee/doo To accept the autosuggestion, hit :kbd:`→` (right arrow) or :kbd:`Control+F`. To accept a single word of the autosuggestion, :kbd:`Alt+→` (right arrow). If the autosuggestion is not what you want, just ignore it. @@ -174,22 +174,22 @@ Tab Completions Press :kbd:`Tab`, and ``fish`` will attempt to complete the command, argument, or path:: - >_ /pri :kbd:`Tab` => /private/ + > /pri :kbd:`Tab` => /private/ If there's more than one possibility, it will list them:: - >_ ~/stuff/s :kbd:`Tab` - ~/stuff/script.sh (Executable, 4.8kB) \mtch{~/stuff/sources/ (Directory)} + > ~/stuff/s :kbd:`Tab` + ~/stuff/script.sh (Executable, 4.8kB) ~/stuff/sources/ (Directory) Hit tab again to cycle through the possibilities. ``fish`` can also complete many commands, like git branches:: - >_ git merge pr :kbd:`Tab` => git merge prompt_designer - >_ git checkout b :kbd:`Tab` - builtin_list_io_merge (Branch) \mtch{builtin_set_color (Branch) busted_events (Tag)} + > git merge pr :kbd:`Tab` => git merge prompt_designer + > git checkout b :kbd:`Tab` + builtin_list_io_merge (Branch) builtin_set_color (Branch) busted_events (Tag) Try hitting tab and see what ``fish`` can do! @@ -199,15 +199,15 @@ Variables Like other shells, a dollar sign performs variable substitution:: - >_ echo My home directory is $HOME + > echo My home directory is $HOME My home directory is /home/tutorial Variable substitution also happens in double quotes, but not single quotes:: - >_ echo "My current directory is $PWD" + > echo "My current directory is $PWD" My current directory is /home/tutorial - >_ echo 'My current directory is $PWD' + > echo 'My current directory is $PWD' My current directory is $PWD @@ -215,8 +215,8 @@ Unlike other shells, ``fish`` has no dedicated `VARIABLE=VALUE` syntax for setti :: - >_ set name 'Mister Noodle' - >_ echo $name + > set name 'Mister Noodle' + > echo $name Mister Noodle @@ -224,8 +224,8 @@ Unlike other shells, ``fish`` has no dedicated `VARIABLE=VALUE` syntax for setti Unlike other shells, variables are not further split after substitution:: - >_ mkdir $name - >_ ls + > mkdir $name + > ls Mister Noodle @@ -235,8 +235,8 @@ You can erase (or "delete") a variable with ``-e`` or ``--erase`` :: - >_ set -e MyVariable - >_ env | grep MyVariable + > set -e MyVariable + > env | grep MyVariable (no output) Exports (Shell Variables) @@ -248,8 +248,8 @@ To give a variable to an external command, it needs to be "exported". Unlike oth :: - >_ set -x MyVariable SomeValue - >_ env | grep MyVariable + > set -x MyVariable SomeValue + > env | grep MyVariable MyVariable=SomeValue It can also be unexported with ``--unexport`` or ``-u``. @@ -266,7 +266,7 @@ Some variables, like ``$PWD``, only have one value. By convention, we talk about Other variables, like ``$PATH``, really do have multiple values. During variable expansion, the variable expands to become multiple arguments:: - >_ echo $PATH + > echo $PATH /usr/bin /bin /usr/sbin /sbin /usr/local/bin @@ -276,23 +276,23 @@ Lists cannot contain other lists: there is no recursion. A variable is a list o Get the length of a list with ``count``:: - >_ count $PATH + > count $PATH 5 You can append (or prepend) to a list by setting the list to itself, with some additional arguments. Here we append /usr/local/bin to $PATH:: - >_ set PATH $PATH /usr/local/bin + > set PATH $PATH /usr/local/bin You can access individual elements with square brackets. Indexing starts at 1 from the beginning, and -1 from the end:: - >_ echo $PATH + > echo $PATH /usr/bin /bin /usr/sbin /sbin /usr/local/bin - >_ echo $PATH[1] + > echo $PATH[1] /usr/bin - >_ echo $PATH[-1] + > echo $PATH[-1] /usr/local/bin @@ -302,15 +302,15 @@ You can also access ranges of elements, known as "slices:" :: - >_ echo $PATH[1..2] + > echo $PATH[1..2] /usr/bin /bin - >_ echo $PATH[-1..2] + > echo $PATH[-1..2] /usr/local/bin /sbin /usr/sbin /bin You can iterate over a list (or a slice) with a for loop:: - >_ for val in $PATH + > for val in $PATH echo "entry: $val" end entry: /usr/bin/ @@ -322,13 +322,13 @@ You can iterate over a list (or a slice) with a for loop:: Lists adjacent to other lists or strings are expanded as :ref:`cartesian products ` unless quoted (see :ref:`Variable expansion `):: - >_ set a 1 2 3 - >_ set 1 a b c - >_ echo $a$1 + > set a 1 2 3 + > set 1 a b c + > echo $a$1 1a 2a 3a 1b 2b 3b 1c 2c 3c - >_ echo $a" banana" + > echo $a" banana" 1 banana 2 banana 3 banana - >_ echo "$a banana" + > echo "$a banana" 1 2 3 banana @@ -339,21 +339,21 @@ Command Substitutions Command substitutions use the output of one command as an argument to another. Unlike other shells, ``fish`` does not use backticks `` for command substitutions. Instead, it uses parentheses:: - >_ echo In (pwd), running (uname) + > echo In (pwd), running (uname) In /home/tutorial, running FreeBSD A common idiom is to capture the output of a command in a variable:: - >_ set os (uname) - >_ echo $os + > set os (uname) + > echo $os Linux Command substitutions are not expanded within quotes. Instead, you can temporarily close the quotes, add the command substitution, and reopen them, all in the same argument:: - >_ touch "testing_"(date +%s)".txt" - >_ ls *.txt + > touch "testing_"(date +%s)".txt" + > ls *.txt testing_1360099791.txt @@ -362,9 +362,9 @@ Unlike other shells, fish does not split command substitutions on any whitespace :: - >_ printf '%s\n' (pkg-config --libs gio-2.0) + > printf '%s\n' (pkg-config --libs gio-2.0) -lgio-2.0 -lgobject-2.0 -lglib-2.0 - >_ printf '%s\n' (pkg-config --libs gio-2.0 | string split " ") + > printf '%s\n' (pkg-config --libs gio-2.0 | string split " ") -lgio-2.0 -lgobject-2.0 -lglib-2.0 @@ -394,8 +394,8 @@ Unlike other shells, ``fish`` stores the exit status of the last command in ``$s :: - >_ false - >_ echo $status + > false + > echo $status 1 @@ -410,13 +410,13 @@ Combiners (And, Or, Not) fish supports the familiar ``&&`` and ``||`` to combine commands, and ``!`` to negate them:: - >_ ./configure && make && sudo make install + > ./configure && make && sudo make install Here, `make` is only executed if `./configure` succeeds (returns 0), and `sudo make install` is only executed if both `./configure` and `make` succeed. fish also supports ``and``, ``or``, and ``not``. The first two are job modifiers and have lower precedence. Example usage:: - >_ cp file1.txt file1_bak.txt && cp file2.txt file2_bak.txt ; and echo "Backup successful"; or echo "Backup failed" + > cp file1.txt file1_bak.txt && cp file2.txt file2_bak.txt ; and echo "Backup successful"; or echo "Backup failed" Backup failed @@ -503,12 +503,12 @@ Functions A ``fish`` function is a list of commands, which may optionally take arguments. Unlike other shells, arguments are not passed in "numbered variables" like ``$1``, but instead in a single list ``$argv``. To create a function, use the ``function`` builtin:: - >_ function say_hello + > function say_hello echo Hello $argv end - >_ say_hello + > say_hello Hello - >_ say_hello everybody! + > say_hello everybody! Hello everybody! @@ -516,13 +516,13 @@ Unlike other shells, ``fish`` does not have aliases or special prompt syntax. Fu You can list the names of all functions with the ``functions`` keyword (note the plural!). ``fish`` starts out with a number of functions:: - >_ functions + > functions alias, cd, delete-or-exit, dirh, dirs, down-or-search, eval, export, fish_command_not_found_setup, fish_config, fish_default_key_bindings, fish_prompt, fish_right_prompt, fish_sigtrap_handler, fish_update_completions, funced, funcsave, grep, help, history, isatty, ls, man, math, nextd, nextd-or-forward-word, open, popd, prevd, prevd-or-backward-word, prompt_pwd, psub, pushd, seq, setenv, trap, type, umask, up-or-search, vared You can see the source for any function by passing its name to ``functions``:: - >_ functions ls + > functions ls function ls --description 'List contents of directory' command ls -G $argv end @@ -533,7 +533,7 @@ Loops While loops:: - >_ while true + > while true echo "Loop forever" end Loop forever @@ -544,14 +544,14 @@ While loops:: For loops can be used to iterate over a list. For example, a list of files:: - >_ for file in *.txt + > for file in *.txt cp $file $file.bak end Iterating over a list of numbers can be done with ``seq``:: - >_ for x in (seq 5) + > for x in (seq 5) touch file_$x.txt end @@ -563,7 +563,7 @@ Unlike other shells, there is no prompt variable like PS1. To display your promp You can define your own prompt:: - >_ function fish_prompt + > function fish_prompt echo "New Prompt % " end New Prompt % @@ -574,7 +574,7 @@ You can define your own prompt:: Multiple lines are OK. Colors can be set via ``set_color``, passing it named ANSI colors, or hex RGB values:: - >_ function fish_prompt + > function fish_prompt set_color purple date "+%m/%d/%y" set_color FF0 @@ -595,16 +595,16 @@ $PATH To prepend /usr/local/bin and /usr/sbin to ``$PATH``, you can write:: - >_ set PATH /usr/local/bin /usr/sbin $PATH + > set PATH /usr/local/bin /usr/sbin $PATH To remove /usr/local/bin from ``$PATH``, you can write:: - >_ set PATH (string match -v /usr/local/bin $PATH) + > set PATH (string match -v /usr/local/bin $PATH) For compatibility with other shells and external commands, $PATH is a :ref:`path variable`, and so will be joined with colons (not spaces) when you quote it: - >_ echo "$PATH" + > echo "$PATH" /usr/local/sbin:/usr/local/bin:/usr/bin and it will be exported like that, and when fish starts it splits the $PATH it receives into a list on colon. @@ -613,7 +613,7 @@ You can do so directly in ``config.fish``, like you might do in other shells wit A faster way is to modify the ``$fish_user_paths`` :ref:`universal variable `, which is automatically prepended to ``$PATH``. For example, to permanently add ``/usr/local/bin`` to your ``$PATH``, you could write:: - >_ set -U fish_user_paths /usr/local/bin $fish_user_paths + > set -U fish_user_paths /usr/local/bin $fish_user_paths The advantage is that you don't have to go mucking around in files: just run this once at the command line, and it will affect the current session and all future instances too. (Note: you should NOT add this line to ``config.fish``. If you do, the variable will get longer each time you run fish!) @@ -629,7 +629,7 @@ It is possible to directly create functions and variables in ``config.fish`` fil :: - >_ cat ~/.config/fish/config.fish + > cat ~/.config/fish/config.fish set -x PATH $PATH /sbin/ @@ -649,7 +649,7 @@ When ``fish`` encounters a command, it attempts to autoload a function for that For example, if you wanted to have a function ``ll``, you would add a text file ``ll.fish`` to ``~/.config/fish/functions``:: - >_ cat ~/.config/fish/functions/ll.fish + > cat ~/.config/fish/functions/ll.fish function ll ls -lh $argv end @@ -657,7 +657,7 @@ For example, if you wanted to have a function ``ll``, you would add a text file This is the preferred way to define your prompt as well:: - >_ cat ~/.config/fish/functions/fish_prompt.fish + > cat ~/.config/fish/functions/fish_prompt.fish function fish_prompt echo (pwd) "> " end @@ -672,12 +672,12 @@ Universal Variables A universal variable is a variable whose value is shared across all instances of ``fish``, now and in the future – even after a reboot. You can make a variable universal with ``set -U``:: - >_ set -U EDITOR vim + > set -U EDITOR vim Now in another shell:: - >_ echo $EDITOR + > echo $EDITOR vim @@ -696,12 +696,12 @@ You can use the following commands for this: Add the fish shell ``/usr/local/bin/fish`` to ``/etc/shells`` with:: - >echo /usr/local/bin/fish | sudo tee -a /etc/shells + > echo /usr/local/bin/fish | sudo tee -a /etc/shells Change your default shell to fish with:: - >chsh -s /usr/local/bin/fish + > chsh -s /usr/local/bin/fish (To change it back to another shell, just substitute ``/usr/local/bin/fish``