fish-shell/doc_src/cmds/command.rst
Johannes Altmanninger 414d9a1eb1 Reference more non-fish shell builtins that have relevant differences
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 
2024-04-20 13:34:08 +02:00

48 lines
1.4 KiB
ReStructuredText

.. _cmd-command:
command - run a program
=======================
Synopsis
--------
.. synopsis::
command [OPTIONS] [COMMANDNAME [ARG ...]]
Description
-----------
.. only:: builder_man
NOTE: This page documents the fish builtin ``command``.
To see the documentation on any non-fish versions, use ``command man command``.
**command** forces the shell to execute the program *COMMANDNAME* and ignore any functions or builtins with the same name.
In ``command foo``, ``command`` is a keyword.
The following options are available:
**-a** or **--all**
Prints all *COMMAND* found in :envvar:`PATH`, in the order found.
**-q** or **--query**
Return 0 if any of the given commands could be found, 127 otherwise.
Don't print anything.
For compatibility, this is also **--quiet** (deprecated).
**-s** or **--search** (or **-v**)
Prints the external command that would be executed, or prints nothing if no file with the specified name could be found in :envvar:`PATH`.
**-h** or **--help**
Displays help about using this command.
Examples
--------
| ``command ls`` executes the ``ls`` program, even if an ``ls`` function also exists.
| ``command -s ls`` prints the path to the ``ls`` program.
| ``command -q git; and command git log`` runs ``git log`` only if ``git`` exists.
| ``command -sq git`` and ``command -q git`` and ``command -vq git`` return true (0) if a git command could be found and don't print anything.