Re: [PATCH v8 5/5] help: respect new common command grouping

From: Junio C Hamano <gitster@pobox.com>
Date: May 18, 2015, 21:39 UTC
Message-ID: <xmqqr3qda7kx.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1431976697-26288-6-git-send-email-sebastien.guimmara@gmail.com>

Sébastien Guimmara  <sebastien.guimmara@gmail.com> writes:

Show 36 quoted lines

> '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:
>
> The typical Git workflow includes:
>
> 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
>    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)
>    log        Show commit logs
>    status     Show the working tree status
>
>    [...]
>
> Helped-by: Eric Sunshine <sunshine@sunshineco.com>
> Signed-off-by: Sébastien Guimmara <sebastien.guimmara@gmail.com>
> ---

I cannot exactly pinpoint what bothers me, but "The typical Git workflow includes:" sounds a bit awkward.

What does a workflow "include"? What are components included in a workflow? Are "starting a repository", "working on a single thing", "collabolating", etc. components that are incuded in a workflow?

If so, the fact that "clone", "init", etc. are "commands that are commonly used in each component of the workflow" is a more important thing to say; in other words, the header does not explain what list it is presenting the user.

Or does a workflow consists of "clone", "init", "add", "mv", etc. that are included in it? Then it is left unexplained what the section headings stand for.

Perhaps something like

	These are common Git commands used in various situations:

may lessen the uneasiness I felt above.  I dunno.

Other than that, this round looks ready for 'next'.

I am not absolutely sure if new dependency on "awk" will not present portability issues, though. So far we only used it in scripts in the fringes and only a few tests.

Thanks.