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

["Sébastien Guimmara" <sebastien.guimmara@gmail.com>]

On 05/07/2015 11:31 AM, Emma Jane Hogbin Westby wrote:
> Sébastien !
>
> This is fantastic! My apologies for jumping in late. Hopefully
> I'm not too late.
>

Thank you :) It's just a very modest contribution though.

>
> Sébastien Guimmara wrote:
>> This v4 includes the following suggestions:
>>
>> In command-list.txt:
>> - Add a [groups] block containing names and description for groups:
>>
>>     [groups]
>>     init                   starting a working area
>>     worktree               working on the current change
>>     remote                 working with others
>>     info                   examining the history and state
>>     history                growing, marking and tweaking your history
> I like these headings / separation.
>
> As you've already "lost" a line to the header, would it make sense to
> add a "see also" into the Guides from here? For example:
>
> starting a working area (see also: git help tutorial)
> working on the current change (see also: git help everyday)
> working with others (see also: git help workflows)
> examining the history and state (see also: git help revisions)
>

I think it's a good idea.

> [...]
>> This produces the following output of $ git help:
>>
>> [...]
>> 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 [...]
>>
>>     * working on the current change:
>>        add        Add file contents to the index
>>        reset      Reset current HEAD to the specified state
> I could not live without status at this stage, and status always tells
> me what I should do next. I'm tempted to see it up here instead...

The layout was not designed to be workflow oriented (even if it appears
so), but rather theme oriented. But I think that a redesign that
introduces the typical Git workflow in a gentle, not intimidating manner
could help beginners realize that Git is extremely simple in its core
principles.

>
>>     * working with others:
>>        fetch      Download objects and refs from another repository
>>        pull       Fetch from and integrate with another repository [...]
>>        push       Update remote refs along with associated objects
>>
>>     * examining the history and state:
>>        log        Show commit logs
>>        status     Show the working tree status
> For this grouping, instead of also having "state", I'd like to see log
> and diff. Perhaps the header is simply "examining the history". This
> narrowing would make more sense to then move status up to "working on
> the current change".
>
>>     * growing, marking and tweaking your history:
>>        branch     List, create, or delete branches
>>        checkout   Checkout a branch or paths to the working tree
>>        commit     Record changes to the repository
>>        diff       Show changes between commits, commit and working [...]
>>        merge      Join two or more development histories together
> By the definition of "tweaking" I would include rebase. Hiding rebase
> from the "common" list will increase its mystique and make people
> even more hesitant to use it. Best to shine some light on it and help
> to make it less scary. I would remove diff from this group as it is
> a non-destructive command.

In a workflow-oriented 'git help', I believe this would make sense.
The patch originally started by examining what is really a 'common'
command, and I estimated that 'rebase' was not that common. However,
since 'rebase' is such a powerful tool and a killer feature of git
(among others), we could mention it in a way that is less intimidating
(see above)

>
> What a wonderful thing to have started, Sébastien ! Thank you. :)
>
Thank you again :)