From: Tay Ray Chuan Date: Mon, 14 Jun 2010 16:49:35 GMT Subject: Re: [PATCH v2] Group the default git help message by topic Message-ID: In-Reply-To: Hi, On Mon, Jun 14, 2010 at 11:31 PM, Scott Chacon wrote: > [snip] > On Sun, Jun 13, 2010 at 11:30 PM, Junio C Hamano 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. >> 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