From 435cf07b7006443b95bfc254bc1581499d53c88e Mon Sep 17 00:00:00 2001 From: Pavla Kratochvilova Date: Tue, 17 Oct 2023 10:41:48 +0200 Subject: [PATCH] doc: Document aliases for command line arguments --- doc/changes.rst | 5 + doc/dnf5.8.rst | 1 + doc/misc/aliases.7.rst | 261 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 267 insertions(+) create mode 100644 doc/misc/aliases.7.rst diff --git a/doc/changes.rst b/doc/changes.rst index 538aa2a466..c2129e8208 100644 --- a/doc/changes.rst +++ b/doc/changes.rst @@ -79,6 +79,11 @@ The functionality is now split to two config options - ``skip_broken`` for the u corresponding command line options ``--skip-broken`` and ``--skip-unavailable`` for commands where it makes sense. +Alias command +------------- +* Dropped. The command is replaced by a different functionality, see + :ref:`Aliases for command line arguments `. + Autoremove command ------------------ * Dropped ```` positional argument since the usecase is sufficiently covered by the ``remove`` command. diff --git a/doc/dnf5.8.rst b/doc/dnf5.8.rst index 3eacd240f5..62406cc20b 100644 --- a/doc/dnf5.8.rst +++ b/doc/dnf5.8.rst @@ -376,6 +376,7 @@ Plugins: | :manpage:`dnf5-repoclosure(8)`, :ref:`Repoclosure command ` Miscellaneous: + | :manpage:`dnf5-aliases(7)`, :ref:`Aliases for command line arguments ` | :manpage:`dnf5-comps(7)`, :ref:`Comps groups and environments ` | :manpage:`dnf5-forcearch(7)`, :ref:`Forcearch parameter ` | :manpage:`dnf5-installroot(7)`, :ref:`Installroot parameter ` diff --git a/doc/misc/aliases.7.rst b/doc/misc/aliases.7.rst new file mode 100644 index 0000000000..1bbc4c110b --- /dev/null +++ b/doc/misc/aliases.7.rst @@ -0,0 +1,261 @@ +.. + Copyright Contributors to the libdnf project. + + This file is part of libdnf: https://github.com/rpm-software-management/libdnf/ + + Libdnf is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 2 of the License, or + (at your option) any later version. + + Libdnf is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with libdnf. If not, see . + +.. _aliases_misc_ref-label: + +################################## +Aliases for command line arguments +################################## + +Description +=========== + +It is possible to define custom aliases which can be then used as dnf commands or options to abbreviate longer +command and option sequences. + +The aliases can be configured in the toml format and the configuration files are taken from these drop-in +directories: + + - ``/usr/share/dnf5/aliases.d/`` + - ``/etc/dnf/dnf5-aliases.d/`` + - ``$XDG_CONFIG_HOME/dnf5/aliases.d/`` + + +Syntax: +------- + +Configuration file must begin with the attribute ``version`` with a value of a supported version, for example: + +.. code-block:: none + + version = '1.0' + +Each alias is defined in a separate section, using ``key = value`` pairs, for example: + +.. code-block:: none + + ['in'] + type = 'command' + attached_command = 'install' + descr = "Alias for 'install'" + +The section name uniquely identifies the alias. It is in a form of a path, i.e. one or more strings separated by dots, +which defines the scope of the alias. For example, string "group.list.in" would identify an alias usable only within +the scope of the group list subcommand. + +There are the following types of aliases: + + - :ref:`command ` + - :ref:`cloned_named_arg ` + - :ref:`named_arg ` + - :ref:`group ` + + +.. _aliases_misc_command_ref-label: + +Type: command +------------- + +The ``command`` alias defines an alias for a command. + +Keys: + - ``type`` with value ``command`` + - ``attached_command`` - path to a command for which this alias is defined + - ``descr`` - description that will be shown in help + - ``group_id`` - a group this alias is part of if any + - ``complete`` - whether bash autocompletion should be used for this alias + - ``attached_named_args`` - options that will be used with the command. The format is an array of inline + tables, each of which must contain an ``id_path`` key to specify the path to an option, and may contain also + a ``value`` key to specify the value of the option. + +The required keys are ``type``, and ``attached_command``. + +Examples: + - Alias ``grouplist`` for ``group list``: + + .. code-block:: none + + ['grouplist'] + type = 'command' + attached_command = 'group.list' + descr = "Alias for 'group list'" + + - Alias ``group.ls`` for ``group list``: + + .. code-block:: none + + ['group.ls'] + type = 'command' + attached_command = 'group.list' + descr = "Alias for 'group list'" + complete = true + + - Alias ``list-fedora-all`` for ``--repo=fedora list --showduplicates``: + + .. code-block:: none + + ['list-fedora-all'] + type = 'command' + attached_command = 'list' + descr = "Alias for '--repo=fedora list --showduplicates'" + complete = true + attached_named_args = [ + { id_path = 'repo', value = 'fedora' }, + { id_path = 'list.showduplicates' } + ] + + +.. _aliases_misc_cloned_named_arg_ref-label: + +Type: cloned_named_arg +---------------------- + +The ``cloned_named_arg`` alias defines another name for a given option. + +Keys: + - ``type`` with value ``cloned_named_arg`` + - ``long_name`` - name of the alias option + - ``short_name`` - one-letter shortcut of the name + - ``source`` - path to the option for which this alias is defined + - ``group_id`` - a group this alias is part of if any + - ``complete`` - whether bash autocompletion should be used for this alias + +The required keys are ``type``, either ``long_name`` or ``short_name``, and ``source``. + +Examples: + - Alias ``--nobest`` for ``--no-best``: + + .. code-block:: none + + ['nobest'] + type = 'cloned_named_arg' + long_name = 'nobest' + source = 'no-best' + + - Alias ``repoquery --list`` or ``repoquery -l`` for ``repoquery --files``: + + .. code-block:: none + + ['repoquery.list'] + type = 'cloned_named_arg' + long_name = 'list' + short_name = 'l' + source = 'repoquery.files' + + +.. _aliases_misc_named_arg_ref-label: + +Type: named_arg +--------------- + +The ``named_arg`` defines an alias that can replace multiple options and can define a value for each. + +Keys: + - ``type`` with value ``named_arg`` + - ``long_name`` - name of the alias option + - ``short_name`` - one-letter shortcut of the name + - ``descr`` - description that will be shown in help + - ``has_value`` - whether the option requires a value. The value is then substituted for ``${}`` strings in the + values of ``attached_named_args``. + - ``value_help`` - the string shown in help for the value (e.g. ``CONFIG_FILE_PATH`` for + ``--config=CONFIG_FILE_PATH``) + - ``const_value`` - default constant value (specified only if the alias does not have a value on the command line) + - ``group_id`` - a group this alias is part of if any + - ``complete`` - whether bash autocompletion should be used for this alias + - ``attached_named_args`` - options that will be used. The format is an array of inline tables, each of which must + contain an ``id_path`` key to specify the path to an option, and may contain also a ``value`` key to specify the + value of the option. + +The required keys are ``type``, and either ``long_name`` or ``short_name``. + +Examples: + - Alias ``list --all-available`` for ``list --showduplicates --available``: + + .. code-block:: none + + ['list.all-available'] + type = 'named_arg' + long_name = 'all-available' + attached_named_args = [ + { id_path = 'list.showduplicates' }, + { id_path = 'list.available' } + ] + + - Alias ``download --dest=DESTDIR`` for ``download --destdir=DESTDIR``: + + .. code-block:: none + + ['download.dest'] + type = 'named_arg' + long_name = 'dest' + has_value = true + value_help = 'DESTDIR' + attached_named_args = [ + { id_path = 'download.destdir' } + ] + + - Alias ``--setflags=TS_FLAGS`` for ``--setopt=tsflags=TS_FLAGS``: + + .. code-block:: none + + ['settsflags'] + type = 'named_arg' + long_name = 'settsflags' + descr = 'Set transaction flags' + has_value = true + value_help = 'TS_FLAGS' + attached_named_args = [ + { id_path = 'setopt', value = 'tsflags=${}' } + ] + + +.. _aliases_misc_group_ref-label: + +Type: group +----------- + +The ``group`` defines a group for multiple commands or options. + +Required keys: + - ``type`` with value ``group`` + - ``header`` - the header of the group as will be shown in help + +The required keys are ``type`` and ``header``. + +The aliases are added to the group using the ``group_id`` key in their respective sections. + +Examples: + - Group ``query-aliases`` for subcommand ``repo`` containing aliases ``repo.ls`` and ``repo.if``: + + .. code-block:: none + + ['repo.query-aliases'] + type = 'group' + header = 'Query Aliases:' + + ['repo.ls'] + type = 'command' + attached_command = 'repo.list' + descr = "Alias for 'repo list'" + group_id = 'query-aliases' + + ['repo.if'] + type = 'command' + attached_command = 'repo.info' + descr = "Alias for 'repo info'" + group_id = 'query-aliases'