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

From: Emma Jane Hogbin Westby <emma.westby@gmail.com>
Date: May 7, 2015, 09:31 UTC
Message-ID: <554B30D5.3050909@emmajane.net>
In-Reply-To: <cover.1430770308.git.sebastien.guimmara@gmail.com>

Sébastien !

This is fantastic! My apologies for jumping in late. Hopefully I'm not too late.

Sébastien Guimmara wrote:

Show 11 quoted lines

> 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)

[...]

Show 12 quoted lines

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

Show 8 quoted lines

>     * 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".

Show 6 quoted lines

>     * 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.

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