mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-26 12:53:13 +00:00
414d9a1eb1
When writing scripts for other shells, it can be confusing and annoying that our `man` function shadows other manual pages, for example `exec(1p)` from [Linux man-pages]. I almost never want to see the fish variant for such contended cases (which obviuosly don't include fish-specific commands like `string`, only widely-known shell builtins). For the contented cases like `exec`, the POSIX documentation is more substantial and useful, since it describes a (sub)set of languages widely used for scripting. Because of this I think we should stop overriding the system's man pages. Nowadays we offer `exec -h` as intuitive way to show the documentation for the fish-specific command (note that `help` is not a good replacement because it uses a web browser). Looking through the contended commands, it seems like for most of them, the fish version is not substantially different from the system version. A notable exception is `read` but I don't think it's a very important one. So I think we should can sacrifice a bit of the native fish-scripting experience in exchange for playing nicer with other shells. I think the latter is more important because scripting is not our focus, the way I see it. So maybe put our manpath at the end. In lieu of that, let's at least have `exec.rst` reference the system variant. [Linux man-pages]: https://www.kernel.org/doc/man-pages/ Closes #10376
67 lines
2.3 KiB
ReStructuredText
67 lines
2.3 KiB
ReStructuredText
.. _cmd-alias:
|
|
|
|
alias - create a function
|
|
=========================
|
|
|
|
Synopsis
|
|
--------
|
|
|
|
.. synopsis::
|
|
|
|
alias
|
|
alias [--save] NAME DEFINITION
|
|
alias [--save] NAME=DEFINITION
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
.. only:: builder_man
|
|
|
|
NOTE: This page documents the fish builtin ``alias``.
|
|
To see the documentation on any non-fish versions, use ``command man alias``.
|
|
|
|
``alias`` is a simple wrapper for the ``function`` builtin, which creates a function wrapping a command. It has similar syntax to POSIX shell ``alias``. For other uses, it is recommended to define a :doc:`function <function>`.
|
|
|
|
If you want to ease your interactive use, to save typing, consider using an :doc:`abbreviation <abbr>` instead.
|
|
|
|
``fish`` marks functions that have been created by ``alias`` by including the command used to create them in the function description. You can list ``alias``-created functions by running ``alias`` without arguments. They must be erased using ``functions -e``.
|
|
|
|
- ``NAME`` is the name of the alias
|
|
- ``DEFINITION`` is the actual command to execute. ``alias`` automatically appends ``$argv``, so that all parameters used with the alias are passed to the actual command.
|
|
|
|
You cannot create an alias to a function with the same name. Note that spaces need to be escaped in the call to ``alias`` just like at the command line, *even inside quoted parts*.
|
|
|
|
The following options are available:
|
|
|
|
**-h** or **--help**
|
|
Displays help about using this command.
|
|
|
|
**-s** or **--save**
|
|
Saves the function created by the alias into your fish configuration directory using :doc:`funcsave <funcsave>`.
|
|
|
|
Example
|
|
-------
|
|
|
|
The following code will create ``rmi``, which runs ``rm`` with additional arguments on every invocation.
|
|
|
|
::
|
|
|
|
alias rmi="rm -i"
|
|
|
|
# This is equivalent to entering the following function:
|
|
function rmi --wraps rm --description 'alias rmi=rm -i'
|
|
rm -i $argv
|
|
end
|
|
|
|
# This needs to have the spaces escaped or "Chrome.app..."
|
|
# will be seen as an argument to "/Applications/Google":
|
|
alias chrome='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome banana'
|
|
|
|
|
|
See more
|
|
--------
|
|
|
|
1. The :doc:`function <function>` command this builds on.
|
|
2. :ref:`Functions <syntax-function>`.
|
|
3. :ref:`Defining aliases <syntax-aliases>`.
|