Re: Git User's Survey 2007 unfinished summary continued

From: Andreas Ericsson <ae@op5.se>
Date: Oct 22, 2007, 07:59 UTC
Message-ID: <471C586A.9030900@op5.se>
In-Reply-To: <Pine.LNX.4.64.0710212308540.25221@racer.site>

Johannes Schindelin wrote:

Show 50 quoted lines

> 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