Skip to content

Commit

Permalink
doc: document sort options in flux-jobs(1)
Browse files Browse the repository at this point in the history
Problem: The --sort option as well as the sort: prefix for format
strings is not documented in flux-jobs(1).

Document the two methods to establish an output sort order in
flux-jobs(1).
  • Loading branch information
grondo committed Oct 21, 2024
1 parent 11c4070 commit b464fff
Showing 1 changed file with 13 additions and 0 deletions.
13 changes: 13 additions & 0 deletions doc/man1/flux-jobs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,13 @@ OPTIONS
configuration snippet for an existing named format may be generated with
:option:`--format=get-config=NAME`.

.. option:: --sort=[-]KEY,..

Sort jobs based on a list of comma separated keys. If a KEY is preceded
by a dash ``-``, then the sort order is reversed. Supported keys match
output field names, e.g. ``id``, ``t_run``, etc. This option overrides
any ``sort:`` prefix specified in the current format.

.. option:: --json

Emit data for selected jobs in JSON format. The data for multiple
Expand Down Expand Up @@ -228,6 +235,12 @@ following is the format used for the default format:
{status_abbrev:>2.2} {ntasks:>6} {nnodes:>6h} \
{contextual_time!F:>8h} {contextual_info}

If the format string begins with ``sort:k1[,k2,...]``, then ``k1[,k2,...]``
will be taken to be a comma-separated list of keys on which to sort
the displayed output. If a sort key starts with ``-``, then the key
will be sorted in reverse order. The sort order embedded in the format
may be overridden on the command line by the :option:`--sort` option.

If a format field is preceded by the special string ``?:`` this will
cause the field to be removed entirely from output if the result would
be an empty string or zero value for all jobs in the listing. E.g.::
Expand Down

0 comments on commit b464fff

Please sign in to comment.