Re: Git User's Survey 2007 unfinished summary continued

[Andreas Ericsson <ae@op5.se>]

Johannes Schindelin wrote:
> Hi,
> 
> On Sun, 21 Oct 2007, Andreas Ericsson wrote:
> 
>> Johannes Schindelin wrote:
>>
>>> On Sun, 21 Oct 2007, Jakub Narebski wrote:
>>>
>>>> On 10/20/07, Steffen Prohaska <prohaska@zib.de> wrote:
>>>>
>>>>> Maybe we could group commands into more categories?
>>>>>
>>>>> plumbing: should be hidden from the 'normal' user. Porcelain
>>>>>    should be sufficient for every standard task.
>>>> The problem is division between what is porcelain and what is 
>>>> plumbing. Some commands are right on border (git-fsck, 
>>>> git-update-index, git-rev-parse comes to mind).
>>> Sorry, but my impression from the latest mails was that the commands 
>>> are fine.  What is lacking is a nice, _small_ collection of 
>>> recommended workflows.  And when we have agreed on such a set of 
>>> workflows, we optimize the hell out of them.  Only this time it is not 
>>> performance, but user-friendliness.
>> http://www.kernel.org/pub/software/scm/git/docs/everyday.html would be a 
>> good starting point, I think.
> 
> I don't think so.  Way too few authors were involved in writing this 
> document, so it is not "typical" in and of itself.
> 
> I'd really like people to respond not so much with broad and general 
> statements to my mail (those statements tend to be rather useless to find 
> how to make git more suitable to newbies), but rather with concrete top 
> ten lists of what they do daily.
> 
> My top ten list:
> 
> - git diff
> - git commit
> - git status
> - git fetch
> - git rebase
> - git pull
> - git cherry-pick
> - git bisect
> - git push
> - git add
> 
> So again, I'd like people who did _not_ tweak git to their likings to tell 
> the most common steps they do.  My hope is that we see things that are 
> good practices, but could use an easier user interface.
> 

I'm not so sure we'd want to hide commands that git-gurus simply do not 
use, such as git-blame. In my opinion, we should just locate the highest 
level available of UI tool that implements a particular feature and have 
that listed in the git[- ]<tab> view.

I doubt many people on this list regularly use git-blame but it's a 
command that's definitely non-trivial to script out using only the 
"proper" commands, and CVS/SVN users expect it to be there, so it's 
probably worth listing anyhow.

Similarly, it might be helpful to have help topics the gdb way, like 
"git help patches". It's one of those things that people have come to 
expect from a software tool, so perhaps we should humor them? Given gits 
"every help topic is a man-page" idiom, this shouldn't require any real 
technical effort.

Such topics should probably include
merge/merges/merging - overview of various ways of putting two lines of 
development back together
patch/patches - how to create, send and apply
tags/branches/refs - what they are, why they're good, link to merging

I'm currently swanked with day-job work, but I'll see if I can get some 
prototype docs done later this week and check if it requires any code 
support. If anyone's well-versed in asciidoc HTML-indexing and wants to 
provide pointers to what I should think about for generating those topic 
menus as html docs, feel free to chuck me an email.

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231