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

Hi,

On Mon, Jun 14, 2010 at 11:31 PM, Scott Chacon [off-list ref] wrote:

[snip]
On Sun, Jun 13, 2010 at 11:30 PM, Junio C Hamano [off-list ref] 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.

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.

quoted

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