Re: [PATCH] user-manual: mention git gui citool (commit, amend)

From: Steffen Prohaska <prohaska@zib.de>
Date: Aug 5, 2007, 12:26 UTC
Message-ID: <D17F92F4-3FF9-46CD-9E55-449C07DE2820@zib.de>
In-Reply-To: <20070804062010.GQ20052@spearce.org>

On Aug 4, 2007, at 8:20 AM, Shawn O. Pearce wrote:

Show 11 quoted lines

>>
>> Though I'd like to keep the main body of the manual focused on the  
>> major
>> command line tools, I'd have no objection to a separate chapter (or
>> appendix?) devoted to git-gui; then you could point directly at that.
>> Would that make sense?
>
> Yea, that makes a lot of sense.  git-gui isn't a full replacement
> for the command line anyway, so I would never suggest a wholesale
> rewrite of the user manual to slant the entire thing towards git-gui.
> Doing so would only point out the many shortcomings in git-gui.  :)

I partially disagree.

When users start to learn git they are mostly interested in how to achieve a specific goal, e.g. how to create a commit. I think most users either accept a command line or a gui, whatever is the easiest and fastest way to do something.

I strongly believe that the sections in the manual should be organized along the tasks that users want to solve and discuss available approaches. Obviously each chapter should start with simple tasks and simple tools (the commandline) and only later add advanced usage scenarios. But I don't think it makes sense to put git gui into a separate chapter.

I personally use the command line for most of my work, but for adding single diff hunks to the index I use git gui. It's much simple than 'git add -i'.

In the chapter on history browsing, the manual pretty early states

"The best way to see how this works is using the gitk(1) command; running gitk now on a git repository and looking for merge commits will help understand how the git organizes history."

which makes absolutely sense to me. If a gui is the best tool to do the job 'understanding history', then there's no reason to first restrict the manual to the command line tools, like 'git log'.

	Steffen