keith
Fork
edit=== Manual Pages: Section 1
{{{ pre
GIT-QSELECT(1) Git-MQ Commands GIT-QSELECT(1)
NAME
git-qselect - manage the active guard state of a patch queue
SYNOPSIS
git qselect [-s | --series] [-v | --verbose]
git qselect [-n | --none] [--pop] [--reapply] [<guard> ...]
DESCRIPTION
The git qselect command is used to manage the active guard state of a
patch queue, and so, in conjunction with the git qguard command,
control the selection of patches which may be pushed.
Depending on the combination of options and arguments specified, the
git qselect command supports three distinct modes of operation, namely,
in order of precedence from highest to lowest:—
1. Invoked when the -n (or --none) option, or any set of one or more
<guard> arguments is specified, the -n (or --none) option, if
specified, initially ensures that any currently active guards are
deactivated; the active guard state is then set to exactly match
any particular set of <guard> arguments which are specified.
Note that, in this highest precedence mode of operation, the effect
of <guard> arguments is not cumulative; thus, specification of the
-n (or --none) option together with any non‐empty set of <guard>
arguments, while permitted, is effectively redundant. However, the
-n (or --none) option is required, when the intent is to clear
currently‐active guards, and leave the queue with all guards
deactivated; in this case, the -n (or --none) option must be
specified, with no accompanying set of <guard> arguments.
2. Invoked only when the -s (or --series) option is specifed, and
neither the -n (or --none) option, nor any <guard> argument is
present, the command will display an alpha‐numerically sorted list
of guards which have been defined by the git qguard command, and
recorded within the series file, regardless of the active guard
state of the patch queue.
The display format, in this mode of operation, may be agumented to
include a count of patches to which each guard is assigned, (and
also a count of patches to which no guards have been assigned,
designated by the reserved pseudo‐guard name “NONE”), by specifying
the -v (or --verbose) option, in conjunction with -s (or --series).
3. Invoked when no <guard> arguments are, and neither the
-n (or --none) option, nor the -s (or --series) option is
specified, this lowest precedence mode of operation simply produces
a display of the currently active guards, if any, or reports that
no guards are active, otherwise.
Note that it is possible for the git qselect, and git qguard commands
to modify the guard state of applied patches, without changing the
applied state of the patch series; invoking git qselect with the --pop,
or --reapply options modifies this behaviour.
OPTIONS
-n, --none
Selects the highest precedence mode of operation, and causes
deactivation of any currently active guards.
--pop
In the case where guarded patches, (in the prevailing guard state
after specified changes, if any, have been instated), precede the
topmost applied patch, pop patches from the stack until no such
patches remain within the applied series.
--reapply
Note the identity of the topmost applied patch, and proceed as for
the --pop option; then, provided the former topmost patch remains
unguarded, in the currently active guard state, push patches,
skipping any which are guarded, until the formerly identified patch
again becomes topmost.
-s, --series
Ignored if any <guard> argument, or the --none option is also
specified; otherwise selects the intermediate precedence mode of
operation, to display a list of all guards which have been defined
in the series file.
-v, --verbose
In the case where the effect of the --series option is dominant,
include patch counts for each defined guard, and the tally of
unguarded patches, in the displayed list.
EXIT STATUS
On successful completion, git qselect reports an exit status code of 0.
Any non‐zero exit status code indicates that an error occurred.
COMPARISON WITH MERCURIAL QUEUES
Inspired by, and for the most part based on behavioural observation of
Mercurial's MQ extension, the git qselect command exhibits
fundamentally the same behaviour as its hg qselect counterpart.
CAVEATS AND BUGS
It may be observed that certain combinations of options, and <guard>
arguments make no sense. Allowing execution to continue, when any such
nonsensical combination is specified, may be considered a bug.
However, this is not caught; rather, execution does continue, on the
basis of selection of the highest precedence applicable operating mode,
and inconsistently specified options are silently ignored.
AUTHOR
Copyright (C) 2019, by Keith Marshall
This man page was written by Keith Marshall <keith@users.osdn.me>, to
accompany the Git-MQ program suite. It is published under the terms of
the GNU Free Documentation Licence, version 1.3, (or any later version
published by the Free Software Foundation), with no Invariant Sections,
no Front‐Cover Texts, and no Back‐Cover Texts.
The Git‐MQ program suite itself is distibruted under the terms of the
GNU General Public Licence, version 3, (or any later version published
by the Free Software Foundation).
Copies of the GNU Free Documentation Licence, and of the GNU General
Public Licence, are included within the Git‐MQ source distribution, in
the files FDL-1.3, and LICENCE, respectively.
SEE ALSO
git-qguard(1), git-qpop(1), git-qpush(1), git-qseries(1)
Git-MQ 1.0 31-Mar-2022 GIT-QSELECT(1)
}}}
A copy of the above, in PDF format, is [https://osdn.net/users/keith/pf/git-mq/wiki/git-qselect.1.manpage/attach/git-qselect.1.pdf available here].