From: Sébastien Guimmara <sebastien.guimmara@gmail.com>
Date: Sun, 03 May 2015 13:54:29 GMT
Subject: Re: [PATCH v2 1/3] git help: group common commands by theme
Message-ID: <55462895.8080108@gmail.com>
In-Reply-To: <xmqqk2wqwg9f.fsf@gitster.dls.corp.google.com>

On 05/03/2015 05:30 AM, Junio C Hamano wrote:
> 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?

Since this help is not only displayed on '$ git help' but also on
'$ git', we can assume it's directed at people not familiar with
git and/or the command line usage.

We could then display headers this way:

The most commonly used git commands are:
    * starting a working area:
       clone      Clone a repository into a new directory
       init       Create an empty Git repository or reinitialize an existing one
    
    * examining the history and state:
       diff       Show changes between commits, commit and working tree, etc
       log        Show commit logs
       show       Show various types of objects
       status     Show the working tree status
       bisect     Find by binary search the change that introduced a bug
       grep       Print lines matching a pattern

    * working on the current change:
       add        Add file contents to the index
       checkout   Checkout a branch or paths to the working tree
       reset      Reset current HEAD to the specified state
       rm         Remove files from the working tree and from the index
       mv         Move or rename a file, a directory, or a symlink
    
    * growing, marking and tweaking your history:
       commit     Record changes to the repository
       rebase     Forward-port local commits to the updated upstream head
       tag        Create, list, delete or verify a tag object signed with GPG
    
    * working with others:
       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
    
    * branching and merging histories:
       branch     List, create, or delete branches
       merge      Join two or more development histories together

This raises a few questions:

1. Is 'bisect' really a common command (from the target audience standpoint)
2. Does 'Forward-port local commits to the updated upstream head' really help
    to grok the idea of 'rebase' ? There are 3 words in this sentence that
    an unfamiliar git user may not be comfortable with : 'forward-port',
    'upstream' and 'head'. I'm not familiar enough with 'rebase' to think of
    a clearer explanation, but what about:
	
	'Rewrite the history of a branch with commits from another branch'