fish-shell/doc_src/faq.hdr

/** \page faq Frequently asked questions

\htmlonly <div class="fish_left_bar fish_left_big"> \endhtmlonly

- <a href='#faq-envvar'>How do I set or clear an environment variable?</a>
- <a href='#faq-login-cmd'>How do I run a command every login? What's fish's equivalent to <tt>.bashrc</tt>?</a>
- <a href='#faq-prompt'>How do I set my prompt?</a>
- <a href='#faq-cmd-history'>How do I run a command from history?</a>
- <a href='#faq-subcommand'>How do I run a subcommand? The backtick doesn't work!</a>
- <a href='#faq-exit-status'>How do I get the exit status of a command?</a>
- <a href='#faq-single-env'>How do I set an environment variable for just one command?</a>
- <a href='#faq-customize-colors'>How do I customize my syntax highlighting colors?</a>
- <a href='#faq-update-manpage-completions'>How do I update man page completions?</a>
- <a href='#faq-cwd-symlink'>Why does cd, pwd and other fish commands always resolve symlinked directories to their canonical path?</a>
- <a href='#faq-cd-implicit'>I accidentally entered a directory path and fish changed directory. What happened?</a>
- <a href='#faq-open'>The open command doesn't work.</a>
- <a href='#faq-default'>How do I make fish my default shell?</a>
- <a href='#faq-titlebar'>I'm seeing weird output before each prompt when using screen. What's wrong?</a>
- <a href='#faq-greeting'>How do I change the greeting message?</a>
- <a href='#faq-history'>Why doesn't history substitution ("!$" etc.) work?</a>
- <a href='#faq-uninstalling'>How do I uninstall fish?</a>

\htmlonly
</div>
<div class="fish_right_bar fish_right_little">
<h1 class="interior_title">Frequently Asked Questions</h1>

\endhtmlonly

\section faq-envvar How do I set or clear an environment variable?

Use the <a href="commands.html#set"><code>set</code></a> command:

<pre>set -x key value
set -e key</pre>

<hr>

\section faq-login-cmd How do I run a command every login? What's fish's equivalent to .bashrc?

Edit the file <tt>~/.config/fish/config.fish</tt>, creating it if it does not
exist. (Note the leading period.)

<hr>

\section faq-prompt How do I set my prompt?

The prompt is the output of the \c fish_prompt function. Put it in
<tt>~/.config/fish/functions/fish_prompt.fish</tt>. For example, a simple
prompt is:
<pre>function fish_prompt
  set_color $fish_color_cwd
  echo -n (prompt_pwd)
  set_color normal
  echo -n ' > '
end</pre>

You can also use the Web configuration tool,
<a href="commands.html#fish_config"><code>fish_config</code></a>, to preview
and choose from a gallery of sample prompts.

<hr>

\section faq-cmd-history How do I run a command from history?

Type some part of the command, and then hit the up or down arrow keys to
navigate through history matches.

<hr>

\section faq-subcommand How do I run a subcommand? The backtick doesn't work!

\c fish uses parentheses for subcommands. For example:

<pre>for i in (ls)
  echo $i
end</pre>

<hr>

\section faq-exit-status How do I get the exit status of a command?

Use the \c $status variable. This replaces the \c $? variable used in some
other shells.

<hr>

\section faq-single-env How do I set an environment variable for just one command?

<i><tt>SOME_VAR=1 command</tt> produces an error: <tt>Unknown command "SOME_VAR=1"</tt>.</i>

Use the \c env command.

<tt>env SOME_VAR=1 command</tt>

You can also declare a local variable in a block:

<pre>begin
  set -lx SOME_VAR 1
  command
end</pre>

<hr>

\section faq-customize-colors How do I customize my syntax highlighting colors?

Use the web configuration tool,
<a href="commands.html#fish_config"><code>fish_config</code></a>, or alter the
<a href="index.html#variables-color">\c fish_color family of environment variables</a>.

<hr>

\section faq-update-manpage-completions How do I update man page completions?

Use the
<a href="commands.html#fish_update_completions"><tt>fish_update_completions</tt></a>
command.

<hr>

\section faq-cwd-symlink Why does cd, $PWD and and various fish commands always resolve symlinked directories to their canonical path?

<i>
For example if ~/images is a symlink to ~/Documents/Images, if I write
'cd images', my prompt will say ~/D/Images, not ~/images.
</i>

Because it is impossible to consistently keep symlinked directories
unresolved. It is indeed possible to do this partially, and many other
shells do so. But it was felt there are enough serious corner cases
that this is a bad idea. Most such issues have to do with how '..' is
handled, and are varitations of the following example:

Writing <code>cd images; ls ..</code> given the above directory
structure would list the contents of ~/Documents, not of ~, even
though using <code>cd ..</code> changes the current directory to ~,
and the prompt, the pwd builtin and many other directory information
sources suggest that the current directory is ~/images and its
parent is ~. This issue is not possible to fix without either making
every single command into a builtin, breaking Unix semantics or
implementing kludges in every single command.

This issue can also be seen when doing IO redirection.

Another related issue is that many programs that operate on recursive
directory trees, like the find command, silently ignore symlinked
directories. For example, <code>find $PWD -name '*.txt'</code>
silently fails in shells that don't resolve symlinked paths.

<hr>

\section faq-cd-implicit I accidentally entered a directory path and fish changed directory. What happened?

If fish is unable to locate a command with a given name, and it starts with '.', '/' or '~', fish will
test if a directory of that name exists. If it does, it is implicitly
assumed that you want to change working directory. For example, the
fastest way to switch to your home directory is to simply press
<code>~</code> and enter.

<hr>

\section faq-open The open command doesn't work.

The \c open command uses the MIME type database and the <code>.desktop</code> files
used by Gnome and KDE to identify filetypes and default actions. If
at least one of these environments is installed, but the open command is
not working, this probably means that the relevant files are installed
in a non-standard location. Consider <a href="index.html#more-help">asking for
more help</a>.

<hr>

\section faq-default How do I make fish my default shell?

If you installed fish manually (e.g. by compiling it, not by using a
package manager), you first need to add fish to the list of shells by
executing the following command (assuming you installed fish in
/usr/local) as root:


<code>echo /usr/local/bin/fish >>/etc/shells</code>

If you installed a prepackaged version of fish, the package manager
should have already done this for you.

In order to change your default shell, type:

<code>chsh -s /usr/local/bin/fish</code>

You may need to adjust the above path to e.g. \c /usr/bin/fish. Use the command <code>which fish</code> if you are unsure of where fish is installed.

Unfortunately, there is no way to make the changes take effect at once.
You will need to log out and back in again.

<hr>

\section faq-titlebar I'm seeing weird output before each prompt when using screen. What's wrong?

Quick answer:

Run the following command in fish:

<pre>
echo 'function fish_title;end' &gt; ~/.config/fish/config.fish
</pre>

Problem solved!

The long answer:

Fish is trying to set the titlebar message of your terminal. While
screen itself supports this feature, your terminal does
not. Unfortunately, when the underlying terminal doesn't support
setting the titlebar, screen simply passes through the escape codes
and text to the underlying terminal instead of ignoring them. It is
impossible detect and resolve this problem from inside fish since fish
has no way of knowing what the underlying terminal type is. For now,
the only way to fix this is to unset the titlebar message, as
suggested above.

Note that fish has a default titlebar message, which will be used if
the fish_title function is undefined. So simply unsetting the
fish_title function will not work.

<hr>

\section faq-greeting How do I change the greeting message?

Change the value of the variable \c fish_greeting or create a \c fish_greeting
function. For example, to remove the greeting use:

<pre>
set fish_greeting
</pre>

<hr>

\section faq-history Why doesn't history substitution ("!$" etc.) work?

Because history substitution is an awkward interface that was invented before
interactive line editing was even possible.  Fish drops it in favor of
perfecting the interactive history recall interface.  Switching requires a
small change of habits: if you want to modify an old line/word, first recall
it, then edit.  E.g. don't type "sudo !!" - first press Up, then Home, then
type "sudo ".

Fish history recall is very simple yet effective:

 - As in any modern shell, the Up arrow recalls whole lines, starting from the last line executed.  A single press replaces "!!", later presses replace "!-3" and the like.
    - If the line you want is far back in the history, type any part of the line and then press Up one or more times.  This will constrain the recall to lines that include this text, and you will get to the line you want much faster.  This replaces "!vi", "!?bar.c" and the like.
 - Alt+Up recalls individual arguments, starting from the last argument in the last line executed.  A single press replaces "!$", later presses replace "!!:4" and the like.
    - If the argument you want is far back in history (e.g. 2 lines back - that's a lot of words!), type any part of it and then press Alt+Up.  This will show only arguments containing that part and you will get what you want much faster.  Try it out, this is very convenient!
    - If you want to reuse several arguments from the same line ("!!:3*" and the like), consider recalling the whole line and removing what you don't need (Alt+D and Alt+Backspace are your friends).

See <a href='index.html#editor'>documentation</a> for more details about line editing in fish.

<hr>

\section faq-uninstalling Uninstalling fish

Should you wish to uninstall fish, first ensure fish is not set as your shell. Run <code>chsh -s /bin/bash</code> if you are not sure. 

Next, do the following (assuming fish was installed to /usr/local):

<pre>
rm -Rf /usr/local/etc/fish /usr/local/share/fish ~/.config/fish
rm /usr/local/share/man/man1/fish*.1
cd /usr/local/bin
rm -f fish mimedb fishd fish_indent
</pre>

*/

\htmlonly
</div>
\endhtmlonly