Re: [PATCH v2 1/3] git help: group common commands by theme

From: Junio C Hamano <gitster@pobox.com>
Date: May 3, 2015, 02:23 UTC
Message-ID: <xmqqk2wqwg9f.fsf@gitster.dls.corp.google.com>
In-Reply-To: <554405D5.9080702@gmail.com>

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

Show 26 quoted lines

> Finally, list_common_cmds_help() prints those common commands by
> groups, skipping a line between each group:
>
> [...]
>
> The most commonly used git commands are:
>    clone      Clone a repository into a new directory
>    init       Create an empty Git repository or reinitialize an existing one
>
>    log        Show commit logs
>    show       Show various types of objects
>    status     Show the working tree status
>
>    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
>
>    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
>
>    commit     Record changes to the repository
>    diff       Show changes between commits, commit and working tree, etc
>    rebase     Forward-port local commits to the updated upstream head
>    tag        Create, list, delete or verify a tag object signed with GPG

What is the target audience? Are they expected to be familiar enough with Git that they can guess what the above grouping is based on without a group header?

I consider myself experienced enough with Git but cannot explain or justify the placement of "diff" in the above list myself, for example. I'd say

 * starting a working area (clone, init)
 * examining the history and state (log, show, status, diff)
 * working on the current change (add, checkout, reset)
 * growing, marking and tweaking your history (commit, tag, rebase)
 * working with others (fetch, pull, push)

might be a more sensible presentation order (and classification).