527ec398 (generate-cmdlist: parse common group commands, 2015-05-21)
replaced generate-cmdlist.sh with a more functional Perl version,
generate-cmdlist.perl. The Perl version gleans named tags from a new
"common groups" section in command-list.txt and recognizes those
tags in "command list" section entries in place of the old 'common'
tag. This allows git-help to, not only recognize, but also group
common commands.

Although the tests require Perl, 527ec398 creates an unconditional
dependence upon Perl in the build system itself, which can not be
overridden with NO_PERL. Such a dependency may be undesirable; for
instance, the 'git-lite' package in the FreeBSD ports tree is
intended as a minimal Git installation (which may, for example, be
useful on servers needing only local clone and update capability),
which, historically, has not depended upon Perl[1].

Therefore, revive generate-cmdlist.sh and extend it to recognize
"common groups" and its named tags. Retire generate-cmdlist.perl.

[1]: http://thread.gmane.org/gmane.comp.version-control.git/275905/focus=276132Signed-off-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

'git help' shows common commands in alphabetical order:

The most commonly used git commands are:
   add        Add file contents to the index
   bisect     Find by binary search the change that introduced a bug
   branch     List, create, or delete branches
   checkout   Checkout a branch or paths to the working tree
   clone      Clone a repository into a new directory
   commit     Record changes to the repository
   [...]

without any indication of how commands relate to high-level
concepts or each other. Revise the output to explain their relationship
with the typical Git workflow:

  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 [...]

  work on the current change (see also: git help everyday)
     add        Add file contents to the index
     reset      Reset current HEAD to the specified state

  examine the history and state (see also: git help revisions)
     log        Show commit logs
     status     Show the working tree status

     [...]
Helped-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NRamsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: NSébastien Guimmara <sebastien.guimmara@gmail.com>
Reviewed-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

command-list.sh, retired in the previous patch, was the only
consumer of the "common" tag, so drop this now-unnecessary
attribute.

before:
    git-add          mainporcelain        common worktree

after:
    git-add          mainporcelain        worktree
Helped-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NSébastien Guimmara <sebastien.guimmara@gmail.com>
Reviewed-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Parse the group block to create the array of group descriptions:

static char *common_cmd_groups[] = {
    N_("starting a working area"),
    N_("working on the current change"),
    N_("working with others"),
    N_("examining the history and state"),
    N_("growing, marking and tweaking your history"),
};

then map each element of common_cmds[] to a group via its index:

static struct cmdname_help common_cmds[] = {
    {"add", N_("Add file contents to the index"), 1},
    {"branch", N_("List, create, or delete branches"), 4},
    {"checkout", N_("Checkout a branch or paths to the ..."), 4},
    {"clone", N_("Clone a repository into a new directory"), 0},
    {"commit", N_("Record changes to the repository"), 4},
    ...
};

so that 'git help' can print those commands grouped by theme.

Only commands tagged with an attribute from the group block are emitted to
common_cmds[].

[commit message by Sébastien Guimmara <sebastien.guimmara@gmail.com>]
Signed-off-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NSébastien Guimmara <sebastien.guimmara@gmail.com>
Reviewed-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The ultimate goal is for "git help" to display common commands in
groups rather than alphabetically. As a first step, define the
groups in a new block, and then assign a group to each
common command.

Add a block at the beginning of command-list.txt:

    init         start a working area (see also: git help tutorial)
    worktree     work on the current change (see also:[...]
    info         examine the history and state (see also: git [...]
    history      grow, mark and tweak your history
    remote       collaborate (see also: git help workflows)

storing information about common commands group, then map each common
command to a group:

    git-add          mainporcelain        common worktree
Helped-by: NEric Sunshine <sunshine@sunshineco.com>
Helped-by: NJunio C Hamano <gitster@pobox.com>
Helped-by: NEmma Jane Hogbin Westby <emma.westby@gmail.com>
Signed-off-by: NSébastien Guimmara <sebastien.guimmara@gmail.com>
Reviewed-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The ultimate goal is for "git help" to classify common commands by
group. Toward this end, a subsequent patch will add a new "common
groups" section to command-list.txt preceding the actual command list.
As preparation, teach existing command-list.txt parsing machinery, which
doesn't care about grouping, to skip over this upcoming "common groups"
section.
Signed-off-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NSébastien Guimmara <sebastien.guimmara@gmail.com>
Reviewed-by: NEric Sunshine <sunshine@sunshineco.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The overwhelming majority of lines were single space aligned,
except a few ones aligned by tabs. Fix inconsistency by using
single space everywhere.
Signed-off-by: NSébastien Guimmara <sebastien.guimmara@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

* mh/multimail-renewal:
  Update git-multimail to version 1.0.2

Documentation fix.

* mg/show-notes-doc:
  rev-list-options.txt: complete sentence about notes matching

* nd/versioncmp-prereleases:
  git tag: mention versionsort.prereleaseSuffix in manpage

* mg/status-v-v:
  status: document the -v/--verbose option

The only changes are to the README files, most notably the list of
maintainers and the project URL.
Signed-off-by: NMichael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

An earlier update to the parser that disects a URL broke an
address, followed by a colon, followed by an empty string (instead
of the port number), e.g. ssh://example.com:/path/to/repo.

* tb/connect-ipv6-parse-fix:
  connect.c: ignore extra colon after hostname

The completion script (in contrib/) contaminated global namespace
and clobbered on a shell variable $x.

* ma/bash-completion-leaking-x:
  completion: fix global bash variable leak on __gitcompappend

The "git push --signed" protocol extension did not limit what the
"nonce" that is a server-chosen string can contain or how long it
can be, which was unnecessarily lax.  Limit both the length and the
alphabet to a reasonably small space that can still have enough
entropy.

* jc/push-cert:
  push --signed: tighten what the receiving end can ask to sign

Document `git status -v`, including its new doubled `-vv` form.
Signed-off-by: NMichael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Make many textual tweaks to the 2.4.0 release notes.
Signed-off-by: NMichael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

"Todo list" is the name that is used in the user-facing documentation.
Signed-off-by: NMichael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NMichael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NMichael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

"diff-highlight" (in contrib/) used to show byte-by-byte
differences, which meant that multi-byte characters can be chopped
in the middle.  It learned to pay attention to character boundaries
(assuming the UTF-8 payload).

* jk/colors:
  diff-highlight: do not split multibyte characters

Test fixes.

* jk/test-annoyances:
  t5551: make EXPENSIVE test cheaper
  t5541: move run_with_cmdline_limit to test-lib.sh
  t: pass GIT_TRACE through Apache
  t: redirect stderr GIT_TRACE to descriptor 4
  t: translate SIGINT to an exit

Documentation update.

* pt/enter-repo-comment-fix:
  enter_repo(): fix docs to match code

Documentation update.

* jz/gitweb-conf-doc-fix:
  gitweb.conf.txt: say "build-time", not "built-time"

* jk/cherry-pick-docfix:
  cherry-pick: fix docs describing handling of empty commits

* iu/fix-parse-options-h-comment:
  parse-options.h: OPTION_{BIT,SET_INT} do not store pointer to defval

* jg/cguide-we-cannot-count:
  CodingGuidelines: update 'rough' rule count

Documentation update.

* jk/pack-corruption-post-mortem:
  howto: document more tools for recovery corruption

Documentation update.

* jn/doc-fast-import-no-16-octopus-limit:
  fast-import doc: remove suggested 16-parent limit

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Code clean-up.

* ps/grep-help-all-callback-arg:
  grep: correctly initialize help-all option

An earlier update to the parser that disects an address broke an
address, followed by a colon, followed by an empty string (instead
of the port number).

* tb/connect-ipv6-parse-fix:
  connect.c: ignore extra colon after hostname

Test fixes for git-p4.

* va/fix-git-p4-tests:
  t9814: guarantee only one source exists in git-p4 copy tests
  git-p4: fix copy detection test
  t9814: fix broken shell syntax in git-p4 rename test