Improve git issue help output

[aronisstav]

Make it look like git's own help:

• Remove repetitive git issue
• Remove repetitive colons
• Remove repetitive fullstops
• Align commands and explanations like git help
• Group commands logically and add headers
• Rephrase some help texts for clarity

[aronisstav]

Git's own help, for reference:

$ git help
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]

These are common Git commands used in various situations:

start a working area (see also: git help tutorial)
   clone      Clone a repository into a new directory
   init       Create an empty Git repository or reinitialize an existing one

work on the current change (see also: git help everyday)
   add        Add file contents to the index
   mv         Move or rename a file, a directory, or a symlink
   reset      Reset current HEAD to the specified state
   rm         Remove files from the working tree and from the index

examine the history and state (see also: git help revisions)
   bisect     Use binary search to find the commit that introduced a bug
   grep       Print lines matching a pattern
   log        Show commit logs
   show       Show various types of objects
   status     Show the working tree status

grow, mark and tweak your common history
   branch     List, create, or delete branches
   checkout   Switch branches or restore working tree files
   commit     Record changes to the repository
   diff       Show changes between commits, commit and working tree, etc
   merge      Join two or more development histories together
   rebase     Reapply commits on top of another base tip
   tag        Create, list, delete or verify a tag object signed with GPG

collaborate (see also: git help workflows)
   fetch      Download objects and refs from another repository
   pull       Fetch from and integrate with another repository or a local branch
   push       Update remote refs along with associated objects

'git help -a' and 'git help -g' list available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.

[aronisstav]

And git issue help output after the commit:

$ git issue help
usage: git issue <command> [<args>]

The following commands are available:

start an issue repository
   clone      Clone the specified remote repository
   init       Create a new issues repository in the current directory

work with an issue
   new        Create a new open issue
   show       Show specified issue (and its comments with -c)
   comment    Add an issue comment
   edit       Edit the specified issue's summary (not yet implemented)
   tag        Add (or remove with -r) a tag
   assign     Assign (or reassign) an issue to a person
   attach     Attach (or remove with -r) a file to an issue
   watcher    Add (or remove with -r) an issue watcher
   close      Remove the open tag, add the closed tag

show multiple issues
   list       List all issues (or just those with a given tag)

synchronize with remote repository
   push       Update remote repository with local changes
   pull       Update local repository with remote changes

help and debug
   help       Display help information about git issue
   log        Output a log of changes made
   git        Run the specified Git command on the issues repository

[dspinellis]

Very nice, thank you! One small problem: unfortunately you updated the wrong file. Look at the comment before your text:

  #
  # The following list is automatically created from README.md by running
  # make sync-docs
  # DO NOT EDIT IT HERE; UPDATE README.md instead
  #

Also, please verify the correctness of all other synced documents after your change.

[aronisstav]

My fault for not seeing the comment. 😃

Will take significantly more time to do this right, but I'll give it a shot.

[dspinellis]

No problem, thank you!

[aronisstav]

Updated and added a test that checks whether the files are in sync. Feedback is welcome 😄

PS. The files weren't in sync after your commit today! 😛

[aronisstav]

I implemented edit as well, but, due to the docs syncing, that feature depends on this PR, so I leave it on my own fork for the time being: aronisstav#1.

Will open a PR here when this PR is merged.

[aronisstav]

@dspinellis

LGTM. Please note that running sync-docs should result in an empty git-status.

That's exactly what this test checks. 😄

[dspinellis]

Excellent! Please ping me when ready to merge.

[aronisstav]

LGTM too. Ready to merge.

[dspinellis]

Thank you! I admired your sed wizardry. Quite rare these days.