From: Sébastien Guimmara Date: Fri, 08 May 2015 18:21:55 GMT Subject: Re: [PATCH 0/3] git help: group common commands by theme Message-ID: <554CFEC3.5030105@gmail.com> In-Reply-To: <554B30D5.3050909@emmajane.net> 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 :)