Re: [PATCH v2] Group the default git help message by topic

From: Tay Ray Chuan <rctay89@gmail.com>
Date: Jun 14, 2010, 16:49 UTC
Message-ID: <AANLkTimNdZO8-lesiGmGm2DeHdhAKbTwzjct-U5P5LLJ@mail.gmail.com>
In-Reply-To: <AANLkTimFUGkYeZaXA7BqX8ghsHX_gGYRK69ScHMXbw2l@mail.gmail.com>

Hi,

On Mon, Jun 14, 2010 at 11:31 PM, Scott Chacon <schacon@gmail.com> wrote:

Show 30 quoted lines

> [snip]
> On Sun, Jun 13, 2010 at 11:30 PM, Junio C Hamano <gitster@pobox.com> wrote:
> [snip]
> To disambiguate what we're talking about here, this is the output that
> is generated from this new patch:
>
> Some commonly used git commands per developer roles are:
>  * Individual Developer (Standalone)
>   init          Create an empty git repository or reinitialize an existing one
>   show-branch   Show branches and their commits
>   log           Show commit logs
>   checkout      Checkout a branch or paths to the working tree
>   add           Add file contents to the index
>   diff          Show changes between commits, commit and working tree, etc
>   commit        Record changes to the repository
>   reset         Reset current HEAD to the specified state
>   merge         Join two or more development histories together
>   rebase        Forward-port local commits to the updated upstream head
>   tag           Create, list, delete or verify a tag object signed with GPG
>  * Individual Developer (Participant)
>   clone         Clone a repository into a new directory
>   pull          Fetch from and merge with another repository or a local branch
>   push          Update remote refs along with associated objects
>   format-patch  Prepare patches for e-mail submission
>  * Integrator
>   am            Apply a series of patches from a mailbox
>   revert        Revert an existing commit
>  * Repository Administration
>   daemon        A really simple server for git repositories
>   shell         Restricted login shell for GIT-only SSH access

On behalf of people too lazy to patch and compile, like myself - thanks.

> [snip]
> As you mention next,
> 'show-branches' is second in the list, which is an issue,

Then perhaps we should do something about Documentation/everyday.txt.

Show 5 quoted lines

> but there
> are several more.  'am', 'revert', 'daemon', 'shell', 'rebase' - none
> of these are appropriate for someone running 'git' and trying to see
> where to start.  If we put those aside, all we have is a big list of
> commands again which adds almost no value to what we had before.

They are placed under the titles 'Integrator' and 'Repository Administration', which, I think, is enough to serve as a 'warning! git-fu ahead' for users who wish to preserve their sanity.

On 'big' - mercurial, which is associated with 'user-friendly', shows a list of 50 commands.

Show 11 quoted lines

>> If readers notice that there are some commands that are out of fashion
>> (e.g. I don't think many people use show-branch anymore in the presence of
>> "log --oneline --graph" and friends) listed in the "git help" output, that
>> is a _good thing_.  It will give us an incentive to keep the Everyday
>> document up to date, and with the effort spent for that, "git help" will
>> automatically be kept up to date as well for free ;-)
>
> That's a fine goal, but I feel like it shouldn't be an "everyday"
> document that generates that output, it should be a "beginner"
> document or a "how to start using Git" document that isn't really in
> the Git source.

I, for one, don't think "git help" is the place beginners go to when they first start off - I sure didn't.

The goal of re-grouping and having a short list of commands is nice, and I see this as useful for people starting to use git, but not for people learning it.

-- 
Cheers,
Ray Chuan