mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-26 21:03:12 +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
61 lines
1.9 KiB
ReStructuredText
61 lines
1.9 KiB
ReStructuredText
.. _cmd-jobs:
|
|
|
|
jobs - print currently running jobs
|
|
===================================
|
|
|
|
Synopsis
|
|
--------
|
|
|
|
.. synopsis::
|
|
|
|
jobs [OPTIONS] [PID | %JOBID]
|
|
|
|
|
|
Description
|
|
-----------
|
|
|
|
.. only:: builder_man
|
|
|
|
NOTE: This page documents the fish builtin ``jobs``.
|
|
To see the documentation on any non-fish versions, use ``command man jobs``.
|
|
|
|
``jobs`` prints a list of the currently running :ref:`jobs <syntax-job-control>` and their status.
|
|
|
|
``jobs`` accepts the following options:
|
|
|
|
**-c** or **--command**
|
|
Prints the command name for each process in jobs.
|
|
|
|
**-g** or **--group**
|
|
Only prints the group ID of each job.
|
|
|
|
**-l** or **--last**
|
|
Prints only the last job to be started.
|
|
|
|
**-p** or **--pid**
|
|
Prints the process ID for each process in all jobs.
|
|
|
|
**-q** or **--query**
|
|
Prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also **--quiet** (but this is deprecated).
|
|
|
|
**-h** or **--help**
|
|
Displays help about using this command.
|
|
|
|
On systems that support this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%.
|
|
|
|
Arguments of the form *PID* or *%JOBID* restrict the output to jobs with the selected process identifiers or job numbers respectively.
|
|
|
|
If the output of ``jobs`` is redirected or if it is part of a command substitution, the column header that is usually printed is omitted, making it easier to parse.
|
|
|
|
The exit status of ``jobs`` is ``0`` if there are running background jobs and ``1`` otherwise.
|
|
|
|
Example
|
|
-------
|
|
|
|
``jobs`` outputs a summary of the current jobs, such as two long-running tasks in this example:
|
|
|
|
.. code-block:: none
|
|
|
|
Job Group State Command
|
|
2 26012 running nc -l 55232 < /dev/random &
|
|
1 26011 running python tests/test_11.py &
|