In commit 1572300 of PR git-lfs#5311 the
"git lfs completion" command was introduced, utilizing the support
provided by the spf13/cobra package to generate tab-completion scripts
for a number of shells.  Short and long help text was provided at
the same time, in the formats offered by the spf13/cobra package.

However, the Git LFS client explicitly overrides the default help
functions of the spf13/cobra package, and replacing them with functions
which output versions of the Git LFS manual pages that are pre-rendered
by our build process.  Thus the long-format help text included in
PR git-lfs#5311 can not be viewed by end users.

As this text is also somewhat terse, having been copied from the
example text provided by the spf13/cobra package, we remove it now
with the expectation that in a subsequent commit in this PR we will
provide a more comprehensive set of instructions in a new manual page
for the "git lfs completion" command.

We also remove the short help text for the "git lfs completion" command,
as the majority of other Git LFS commands (with the exception of the
"git lfs help" command) do not define these text strings, and in a
subsequent commit in this PR we will suppress their inclusion in the
command lists output by the completion scripts, so as not to make
the formatting of those lists irregular and uneven.

In commit 1572300 of PR git-lfs#5311 the
"git lfs completion" command was introduced, utilizing the support
provided by the spf13/cobra package to generate tab-completion scripts
for a number of shells, including the Bash, fish, and Zsh shells.

We now reorder the list of these shells and their relevant case switches
so they are in alphabetical order.

In commit 1572300 of PR git-lfs#5311 the
"git lfs completion" command was introduced, utilizing the support
provided by the spf13/cobra package to generate tab-completion scripts
for a number of shells, including the Bash shell.  The completion
script for the Bash shell is currently generated using the spf13/cobra
package's legacy implementation, which is returned by the
(*Command).GenBashCompletion() method.

However, the spf13/cobra package's maintainers advise using their
newer implementation of tab-completion for the Bash shell, which is
returned by the (*Command).GenBashCompletionV2() method, as this
version of the script is shorter and aligned with the tab-completion
scripts now generated for other shells.

In particular, the new version of the Bash tab-completion script has
support for the program to return custom, dynamic completion lists using
per-command functions.  While the current Git LFS client does not
implement any of these ValidArgsFunction() or RegisterFlagCompletionFunc()
functions, we anticipate doing so in the future so as to be able to
provide lists of Git-specific values such as ref and remote names,
when appropriate for a particular Git LFS command.

Note that in order for the new Bash completion script for Git LFS to
integrate properly with the Bash completion script from the Git project,
we have to revise the script generated by the spf13/cobra package so it
rewrites the set of command words when the user types "git lfs ...[Tab]"
such that the initial two words are replaced with the single word
"git-lfs".  This requires a more substantial replacement of a portion
of the generated script than was the case with the legacy implementation.

In a prior commit in this PR we revised the "git lfs completion" command
so it would generate a tab-completion script for the Bash shell using
the newer implementation offered by the spf13/cobra package's
(*Command).GenBashCompletionV2() method, and in doing so also added
a search-and-replace operation to revise the generated script such that
it would integrate with Git's own tab-completion script for Bash.

We already perform a similar search-and-replace operation to revise
the script generated for the Zsh shell by the spf13/cobra package's
(*Command).GenZshCompletion() method.  These script revisions were
introduced in commit 4c9987d of PR git-lfs#5311
so that the tab-completion script for Git LFS would integrate with the
Zsh shell's native tab-completion for Git.

We now refactor the script generation and modification for Zsh to more
closely align with that used for the Bash shell, which should also
slightly improve the clarity of the code and make its purpose more
obvious.

In commit 1572300 of PR git-lfs#5311 the
"git lfs completion" command was introduced, utilizing the support
provided by the spf13/cobra package to generate tab-completion scripts
for a number of shells, including the Bash, fish, and Zsh shells.
These scripts make use of "hidden"  __complete and __completeNoDesc
commands, also implemented by the spf13/cobra package, which the
shell completion functions may query to retrieve dynamic lists of
command names and flags from the Git LFS client.

At present, the __complete command is used, which also returns any
short help text defined each command.  This additional descriptive
text is then presented to the user if they are running a shell like
Zsh whose completion system supports the display of such hints.

However, as we only define short help text for a single Git LFS
command, namely the "git lfs help" command, the display of this
one text string causes the columnar display of available command
names to be prefaced with a single "help" line when the user
types "git lfs [Tab]":

  help             -- Help about any command
  checkout         fsck             post-checkout    status
  clean            install          post-commit      track
  ...              ...              ...              ...

This irregularity makes the display output less helpful and more
difficult to parse than if we simply suppress the inclusion of the
per-command descriptions entirely, so we do so by setting the
appropriate flags or using a different script generation method
of the spf13/cobra package.

Note that we then also need to update the name of the __complete
command to __completeNoDesc in the search-and-replace operation we
perform on the script generated for the Zsh shell.

We can always revisit this choice in the future should we choose
to add short help text to all our command definitions.  This would
require refactoring our NewCommand() and RegisterCommand() functions
to accept the per-command text strings as extra parameters.

In commit 1572300 of PR git-lfs#5311 the
"git lfs completion" command was introduced, utilizing the support
provided by the spf13/cobra package to generate tab-completion scripts
for a number of shells, including the Bash, fish, and Zsh shells.
No tests were added at the same time, however, so we do so now.

The new tests are simple and just confirm that the "git lfs completion"
command generates the expected error messages if it is not given an
expected shell name as an argument, and that when one of the supported
shell names is provided, the command generates the expected script.

We do not attempt to test the functionality of the generated scripts.

Although these tests are quite basic, they should help alert us to
any potential regressions caused by an upgrade of the spf13/cobra
package.

In particular, if the scripts generated by that package for the Bash
or Zsh shells change such that the search-and-replace operations
we perform on the scripts cease to function, the "git lfs completion"
command will still succeed but may produce a script which no longer
integrates well with the tab-completion scripts for Git itself.

Since we have now have archived copies of the current scripts as test
fixtures, the tests will fail when the generated scripts are different.
This should alert us to the fact that we need to check the new
script output and confirm that it still works with Git tab-completion
on the affected shells, and if not, revise our search-and-replace
operations accordingly.

In commit 1572300 of PR git-lfs#5311 the
"git lfs completion" command was introduced, utilizing the support
provided by the spf13/cobra package to generate tab-completion scripts
for a number of shells, including the Bash, fish, and Zsh shells.

However, no manual page was added at the same time, although help text
was included using the spf13/cobra package's format for long command
descriptions.  Unfortunately, as described in an earlier commit in this
PR, the Git LFS client overrides the default help functions defined by
the spf13/cobra package and so there was no way for a user to access
this long-format help text for the "git lfs completion" command.

We therefore removed the original help text for the command, and now
reintroduce a revised and expanded version of the text in the form of
a manual page for the git-lfs-completion(1) command.

The full text of this new manual page attempts to explain the features
and limitations of the current tab-completion scripts, especially the fact
that the Git LFS client does not yet offer suggested lists of terms
specific to Git, such as ref or remote names, but that the tab-completion
scripts for Git LFS should integrate well with the tab-completion
scripts for Git itself, provided the correct one is used for a given
shell.

We also try to include examples of the configuration of tab-completion
for each type of shell and for both a user's current session as well
as for future sessions.  Complete documentation of all such per-shell
configuration options is beyond the scope of the Git LFS project,
of course, but we aim to provide a sufficient overview so as to guide
users to a working solution and forestall support requests as much
as possible.