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

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

[Steffen Prohaska]

git gui is especially useful because it allows to select diff hunks.
Now it is at least mentioned in the user-manual.

Signed-off-by: Steffen Prohaska <prohaska@zib.de>
---
 Documentation/user-manual.txt |   21 ++++++++++++++++++++-
 1 files changed, 20 insertions(+), 1 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 0071cd0..de4ec0b 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1079,6 +1079,24 @@ $ git diff HEAD	    # difference between HEAD and working tree; what
 $ git status	    # a brief per-file summary of the above.
 -------------------------------------------------
 
+Another approach for creating commits is git gui:
+
+-------------------------------------------------
+$ git gui citool
+-------------------------------------------------
+
+starts the commit tool (Note, "`git gui`" starts the full gui, which
+provides more options).
+
+Beyond the basic operation of staging and unstaging complete files,
+git gui can also selectively stage diff hunks.  You can do so by
+selecting a modified or staged file and right-click on the diff view
+in the lower part of the gui. A pop-up will appear that lets you
+select a specific hunk and stage or unstage it for the next commit.
+This is particular useful for slicing large, ugly commits into smaller
+pieces, for example when cherry-picking (see
+<<reordering-patch-series>>).
+
 [[creating-good-commit-messages]]
 Creating good commit messages
 -----------------------------
@@ -2480,7 +2498,8 @@ $ gitk origin..mywork &
 And browse through the list of patches in the mywork branch using gitk,
 applying them (possibly in a different order) to mywork-new using
 cherry-pick, and possibly modifying them as you go using commit
---amend.
+--amend. git gui may be especially useful to amend commits as it
+lets you selectively stage and unstage single diff hunks.
 
 Another technique is to use git-format-patch to create a series of
 patches, then reset the state to before the patches:
-- 
1.5.3.rc3.122.g4978

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

[Shawn O. Pearce]

Steffen Prohaska <prohaska@zib.de> wrote:
> git gui is especially useful because it allows to select diff hunks.
> Now it is at least mentioned in the user-manual.
 
> +Another approach for creating commits is git gui:
> +
> +-------------------------------------------------
> +$ git gui citool
> +-------------------------------------------------

Actually `git citool` is an alias for `git gui citool`.  Because the
former is much faster to type when you want to make a quick commit.
:-)

> +
> +starts the commit tool (Note, "`git gui`" starts the full gui, which
> +provides more options).

But this note is also really useful.  So maybe talking about the
longer form in the user manual is a good way to introduce git-gui.

> +Beyond the basic operation of staging and unstaging complete files,
> +git gui can also selectively stage diff hunks.  You can do so by
> +selecting a modified or staged file and right-click on the diff view
> +in the lower part of the gui. A pop-up will appear that lets you
> +select a specific hunk and stage or unstage it for the next commit.
> +This is particular useful for slicing large, ugly commits into smaller
> +pieces, for example when cherry-picking (see
> +<<reordering-patch-series>>).

Yes.  Now if only someone would teach it how to let you highlight a
section and stage/unstage just the selection.  Never mind splitting
a hunk.  Selection based stage/unstage would really be cool...
especially when combined with git-stash.  Where you could first
stash everything, reset back to the last committed state, then
selectively unstash changes into the working directory, test them,
stage everything for commit, then unstash more, etc...

Since git-stash is modeled as a commit, it could also work for
cherry-picking.  Which is very useful when cleaning up a series.
Hmm.  Wishlist for git-gui!

> @@ -2480,7 +2498,8 @@ $ gitk origin..mywork &
>  And browse through the list of patches in the mywork branch using gitk,
>  applying them (possibly in a different order) to mywork-new using
>  cherry-pick, and possibly modifying them as you go using commit
> ---amend.
> +--amend. git gui may be especially useful to amend commits as it
> +lets you selectively stage and unstage single diff hunks.

Yes.  Except git-gui (currently) destroys the author information
when it does an amend.  Bad git-gui!  Bad!  No prize for you!  :-)

-- 
Shawn.

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

[J. Bruce Fields]

On Mon, Jul 30, 2007 at 06:11:20PM +0200, Steffen Prohaska wrote:
> git gui is especially useful because it allows to select diff hunks.
> Now it is at least mentioned in the user-manual.

Hm, OK.  I think the user manual's only departures from the commandline
right now are a few mentions of gitk (which don't actually explain how
to use it; I assume that's self-explanatory).

But this seems interesting enough to be worth a mention, thanks.

> +Another approach for creating commits is git gui:
> +
> +-------------------------------------------------
> +$ git gui citool
> +-------------------------------------------------
> +
> +starts the commit tool (Note, "`git gui`" starts the full gui, which
> +provides more options).
> +
> +Beyond the basic operation of staging and unstaging complete files,
> +git gui can also selectively stage diff hunks.  You can do so by
> +selecting a modified or staged file and right-click on the diff view
> +in the lower part of the gui. A pop-up will appear that lets you
> +select a specific hunk and stage or unstage it for the next commit.
> +This is particular useful for slicing large, ugly commits into smaller
> +pieces, for example when cherry-picking (see
> +<<reordering-patch-series>>).

I wonder whether we could get away with just the brief list of features
("lets you view changes in the index and the working file, lets you
individually select diff hunks for inclusion in the index"), and leave
the how-to stuff to online guit-gui help, if it's necessary?

Also, I like the verb "stage" as a way to explain the part of the index
file in creating commits, but I've been consistently using the word
"index" throughout the user manual, and I think that's consistent with
the rest of the documentation--so don't avoid it here.

--b.

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

[Steffen Prohaska]

On Aug 2, 2007, at 8:18 PM, J. Bruce Fields wrote:

> On Mon, Jul 30, 2007 at 06:11:20PM +0200, Steffen Prohaska wrote:

>> +Another approach for creating commits is git gui:
>> +
>> +-------------------------------------------------
>> +$ git gui citool
>> +-------------------------------------------------
>> +
>> +starts the commit tool (Note, "`git gui`" starts the full gui, which
>> +provides more options).
>> +
>> +Beyond the basic operation of staging and unstaging complete files,
>> +git gui can also selectively stage diff hunks.  You can do so by
>> +selecting a modified or staged file and right-click on the diff view
>> +in the lower part of the gui. A pop-up will appear that lets you
>> +select a specific hunk and stage or unstage it for the next commit.
>> +This is particular useful for slicing large, ugly commits into  
>> smaller
>> +pieces, for example when cherry-picking (see
>> +<<reordering-patch-series>>).
>
> I wonder whether we could get away with just the brief list of  
> features
> ("lets you view changes in the index and the working file, lets you
> individually select diff hunks for inclusion in the index"), and leave
> the how-to stuff to online guit-gui help, if it's necessary?

Maybe, this would be sufficient. I mentioned the pop-up explicitly
because it wasn't obvious to me right away. The reason might be that
my brain adjusted too much to the Mac I'm using. Right-clicking and
pop-ups are rarely used on Macs as the only access point to essential
features, such as selectively staging diff hunks. Typically an icon
or menu entry guides you explicitly to every feature. Pop-ups are only
used for 'optimized' access but never as the only access point.


> Also, I like the verb "stage" as a way to explain the part of the  
> index
> file in creating commits, but I've been consistently using the word
> "index" throughout the user manual, and I think that's consistent with
> the rest of the documentation--so don't avoid it here.

"staging/unstaging" is how git gui calls adding/removing files to and
from the index.

	Steffen

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

[J. Bruce Fields]

On Fri, Aug 03, 2007 at 12:24:10AM +0200, Steffen Prohaska wrote:
>
> On Aug 2, 2007, at 8:18 PM, J. Bruce Fields wrote:
>
>> I wonder whether we could get away with just the brief list of features
>> ("lets you view changes in the index and the working file, lets you
>> individually select diff hunks for inclusion in the index"), and leave
>> the how-to stuff to online guit-gui help, if it's necessary?
>
> Maybe, this would be sufficient. I mentioned the pop-up explicitly
> because it wasn't obvious to me right away.

I took a quick look and it wasn't obvious to me either.  It'd be nice if
this could be fixed in the interface or the documentation in git-gui
itself instead of here, but perhaps saying it here is easiest for now.

>> Also, I like the verb "stage" as a way to explain the part of the index
>> file in creating commits, but I've been consistently using the word
>> "index" throughout the user manual, and I think that's consistent with
>> the rest of the documentation--so don't avoid it here.
>
> "staging/unstaging" is how git gui calls adding/removing files to and
> from the index.

I understand what you meant, but a reader of the user manual at this
point might not, since it's been consistently saying things like "to add
the contents of a new file to the index, use git add".  So we should use
the same language here.  Unless we want to update the whole thing to use
"stage" and "unstage".  I'd rather not.

--b.

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

[Junio C Hamano]

"J. Bruce Fields" <bfields@fieldses.org> writes:

> I wonder whether we could get away with just the brief list of features
> ("lets you view changes in the index and the working file, lets you
> individually select diff hunks for inclusion in the index"), and leave
> the how-to stuff to online guit-gui help, if it's necessary?

Let's do that.

> Also, I like the verb "stage" as a way to explain the part of the index
> file in creating commits, but I've been consistently using the word
> "index" throughout the user manual, and I think that's consistent with
> the rest of the documentation--so don't avoid it here.

I tend to agree.  The verb "to stage" is really just a way to
say "the act of adding contents to the index" and explain what
it implies (i.e. "prepare it to be included in the next commit").
Saying "you can _think_ of the index as a staging area" is fine,
but the official name of that thing is "the index", and I do not
think avoiding that term adds clarity to the documentation.

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

[Shawn O. Pearce]

Steffen Prohaska <prohaska@zib.de> wrote:
> Maybe, this would be sufficient. I mentioned the pop-up explicitly
> because it wasn't obvious to me right away. The reason might be that
> my brain adjusted too much to the Mac I'm using. Right-clicking and
> pop-ups are rarely used on Macs as the only access point to essential
> features, such as selectively staging diff hunks. Typically an icon
> or menu entry guides you explicitly to every feature. Pop-ups are only
> used for 'optimized' access but never as the only access point.

Steffen, you seem to be more in-tune with the Mac UI standards
than I am.  Any suggestions on what I can do in git-gui to make
this feature more obvious to users?

I myself use a Mac OS X based PowerBook as my primary development
system, but I have to admit, I'm not the best GUI developer that has
ever walked on this planet.  Far far far from it.  I get by, if that.
The fact that git-gui is even usable by mortals is a minor miracle.

So I'd really love to do better.  But frankly I'm at a loss here
and just don't know what sort of change to make.


Side note: Someone recently asked me how to move individual files
to the left side of the UI (to stage them).  Apparently this person
had been using git-gui for months by just clicking "Add Existing"
(recently renamed to "Stage Changed").  It never occurred to the
user to try clicking the file's individual icons.  Or to select
the files they were interested in and look for a menu option that
might work on that selection.

-- 
Shawn.

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

[Shawn O. Pearce]

"J. Bruce Fields" <bfields@fieldses.org> wrote:
> > +Beyond the basic operation of staging and unstaging complete files,
> > +git gui can also selectively stage diff hunks.  You can do so by
...
> 
> I wonder whether we could get away with just the brief list of features
> ("lets you view changes in the index and the working file, lets you
> individually select diff hunks for inclusion in the index"), and leave
> the how-to stuff to online guit-gui help, if it's necessary?

Online help?  In git-gui?  :-)

We don't have an online help system yet.  Basically no documentation
has been written for git-gui.  No thought has been put into how one
should be organized, maintained, or displayed to the poor human
who is just trying to learn more about Git and this gui thing it
came with.

Yes, Help->Online Documentation is abvailable to most users, but
that just opens your web browser (if it can find one) and points
it to kernel.org's git manual.  Not exactly the best material for
learning more about git-gui itself.

-- 
Shawn.

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

[Steffen Prohaska]

On Aug 3, 2007, at 12:31 AM, J. Bruce Fields wrote:

>>> Also, I like the verb "stage" as a way to explain the part of the  
>>> index
>>> file in creating commits, but I've been consistently using the word
>>> "index" throughout the user manual, and I think that's consistent  
>>> with
>>> the rest of the documentation--so don't avoid it here.
>>
>> "staging/unstaging" is how git gui calls adding/removing files to and
>> from the index.
>
> I understand what you meant, but a reader of the user manual at this
> point might not, since it's been consistently saying things like  
> "to add
> the contents of a new file to the index, use git add".  So we  
> should use
> the same language here.  Unless we want to update the whole thing  
> to use
> "stage" and "unstage".  I'd rather not.

Agree. But we could briefly introduce git gui's dialect, something like

"git gui lets you select files (use menu 'Commit > Stage to Commit') or
individually diff hunks (use 'Stage Hunk For Commit' in context menu of
diff view) for inclusion in the index."

	Steffen

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

[J. Bruce Fields]

On Thu, Aug 02, 2007 at 11:01:01PM -0400, Shawn O. Pearce wrote:
> Steffen, you seem to be more in-tune with the Mac UI standards
> than I am.  Any suggestions on what I can do in git-gui to make
> this feature more obvious to users?
> 
> I myself use a Mac OS X based PowerBook as my primary development
> system, but I have to admit, I'm not the best GUI developer that has
> ever walked on this planet.  Far far far from it.

You're way ahead of me!

> So I'd really love to do better.  But frankly I'm at a loss here
> and just don't know what sort of change to make.

The one thing that struck me when I fired up git-gui was that it wasn't
obvious to me which things I should try clicking on.

For example: the buttons, drop-down menus, and check-boxes all cry out
to be played with.  But the filenames in the lists at the top are less
obvious, and it might never have occurred to me on my own to right-click
on the diff hunks at the bottom.  That just looks like passive colorized
text to me.

I don't know what sort of user-interface conventions say "play with
me!", though.  Random ideas:

	- maybe the cursor should change shape over the diff hunks (or
	  just the headers?)
	- maybe buttons, hunk headers, file names, etc., should all be
	  in the same color?
	- maybe the hunk headers could benefit from a little more
	  decoration?  I don't know how to do that without just making
	  the display look more cluttered, though.
	- maybe left-clicking on diff hunks should do something too?

I dunno.

--b.

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

[J. Bruce Fields]

On Fri, Aug 03, 2007 at 07:08:44AM +0200, Steffen Prohaska wrote:
>
> On Aug 3, 2007, at 12:31 AM, J. Bruce Fields wrote:
>
>>>> Also, I like the verb "stage" as a way to explain the part of the index
>>>> file in creating commits, but I've been consistently using the word
>>>> "index" throughout the user manual, and I think that's consistent with
>>>> the rest of the documentation--so don't avoid it here.
>>>
>>> "staging/unstaging" is how git gui calls adding/removing files to and
>>> from the index.
>>
>> I understand what you meant, but a reader of the user manual at this
>> point might not, since it's been consistently saying things like "to add
>> the contents of a new file to the index, use git add".  So we should use
>> the same language here.  Unless we want to update the whole thing to use
>> "stage" and "unstage".  I'd rather not.
>
> Agree. But we could briefly introduce git gui's dialect, something like
>
> "git gui lets you select files (use menu 'Commit > Stage to Commit') or
> individually diff hunks (use 'Stage Hunk For Commit' in context menu of
> diff view) for inclusion in the index."

Sounds good to me.  Somebody do that!

--b.

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

[J. Bruce Fields]

On Thu, Aug 02, 2007 at 11:04:59PM -0400, Shawn O. Pearce wrote:
> Online help?  In git-gui?  :-)
> 
> We don't have an online help system yet.  Basically no documentation
> has been written for git-gui.  No thought has been put into how one
> should be organized, maintained, or displayed to the poor human
> who is just trying to learn more about Git and this gui thing it
> came with.
> 
> Yes, Help->Online Documentation is abvailable to most users, but
> that just opens your web browser (if it can find one) and points
> it to kernel.org's git manual.  Not exactly the best material for
> learning more about git-gui itself.

Fair enough.

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?

--b.

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

[Shawn O. Pearce]

"J. Bruce Fields" <bfields@fieldses.org> wrote:
> On Thu, Aug 02, 2007 at 11:04:59PM -0400, Shawn O. Pearce wrote:
> > Online help?  In git-gui?  :-)
> > 
> > We don't have an online help system yet.
> 
> Fair enough.
> 
> 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 haven't explored any in-Tk rendering options yet, been too busy
with other projects.  Ideally I'd like to just render the asciidoc
markup directly, but I don't think anyone has done an asciidoc
viewer for Tk.  I can't imagine it would be that difficult to get
some sort of parser working though...


But at this point in git (and git-gui's) life I think it would
be very worthwhile to devote an entire (new) chapter to git-gui,
maybe as part of git 1.5.4/git-gui 0.9.0.  I think we're far too
late in the 1.5.3 cycle to do it now.  I personally won't have the
time to even try to rough draft something anytime soon, let alone
let others copy-edit me before Juino releases 1.5.3.  :)

Being bundled with core git has brought git-gui a sizeable and
growing userbase, and more and more users are discovering it
each day.  We're now seeing it be translated into many different
languages, and it is a somewhat core part of the MSYS port as many
Windows users prefer to click in GUIs over type in cmd.exe terminal
windows (can't say I blame them, cmd.exe is aweful!).

In other words I think git-gui should get roughly as much attention
from the user manual as git-add/rm/mv/commit/checkout/branch get,
as it offers the same feature set.  But it shouldn't distract from
the command line part of the manual.

Maybe we should write parts of the manual in a "choose your own
adventure style" and use different chapters for different paths.
I think users can easily decide between the command line "i like to
type" vs. the gui "i like to click" paths and focus their attention
to the material they are most interested in.  :-)

-- 
Shawn.

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

[Shawn O. Pearce]

"J. Bruce Fields" <bfields@fieldses.org> wrote:
> On Thu, Aug 02, 2007 at 11:01:01PM -0400, Shawn O. Pearce wrote:
> > So I'd really love to do better.  But frankly I'm at a loss here
> > and just don't know what sort of change to make.
> 
> The one thing that struck me when I fired up git-gui was that it wasn't
> obvious to me which things I should try clicking on.

Yea, that I have noticed with other newbies.  I have recently had
the chance to observe a few new users work with git-gui for the
first time and I have noticed that they just don't quite know what
to poke at and experiment with.  Unlike with many other applications
where its more obvious what's there for the poking...
 
> For example: the buttons, drop-down menus, and check-boxes all cry out
> to be played with.  But the filenames in the lists at the top are less
> obvious, and it might never have occurred to me on my own to right-click
> on the diff hunks at the bottom.  That just looks like passive colorized
> text to me.

It doesn't just look like colored text to me anymore.  Which is a
huge problem for me as an interface designer.  I know what's there.

BTW, the reason why there's a context menu in the diff viewer?
I right clicked in there one day and nothing happened.  The fact
that nothing happen surprised the hell out of me.  Even though I
had written all of that code myself.  So I went off and added
that context menu.

Later I realized I wanted to just stage that hunk.  I could click
on it all I want, but the $@!*@(!@* computer didn't do what I really
wanted it to.  So stage hunk was born and added to the context menu.

That experience is actually true of much of the git-gui UI.  Things
happen there only because I've actually tried to do something,
only to shock myself when I find out it doesn't work!  I promptly
write the patch and contribute it.  :)
 
> I don't know what sort of user-interface conventions say "play with
> me!", though.  Random ideas:
> 
> 	- maybe the cursor should change shape over the diff hunks (or
> 	  just the headers?)

That's actually a pretty cool idea.  I might play with it just to
see how I feel about the cursor changing and if it gives me any
ideas about what might happen under it.  Though as I write this
email I'm thinking that if the cursor changed shape when it was
over the diff hunk header I'd try to left-click the hunk header to
get a reaction from the computer.

> 	- maybe buttons, hunk headers, file names, etc., should all be
> 	  in the same color?
> 	- maybe the hunk headers could benefit from a little more
> 	  decoration?  I don't know how to do that without just making
> 	  the display look more cluttered, though.
> 	- maybe left-clicking on diff hunks should do something too?

I just had a thought of putting an actual button icon in the first
column of the hunk header lines.  If it looks enough like a button
icon thingy, users might just click on it.  And when they do we
can present that diff pane context menu, and look, they can stage
their hunks!  ;-)

Just a thought.  Utterly random too.  Musta been that alpha particle
slamming into a neuron.

Thanks for the ideas.  Its certainly given me some things to
experiment with in the next week or so when I can find the time.

-- 
Shawn.

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

[David Kastrup]

"Shawn O. Pearce" <spearce@spearce.org> writes:

> I haven't explored any in-Tk rendering options yet, been too busy
> with other projects.  Ideally I'd like to just render the asciidoc
> markup directly, but I don't think anyone has done an asciidoc
> viewer for Tk.  I can't imagine it would be that difficult to get
> some sort of parser working though...

With regard to my Texinfo proposal in a different thread, it must be
mentioned that "tkinfo" can be used as an embedded info viewer in
existing applications.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[J. Bruce Fields]

On Sat, Aug 04, 2007 at 02:20:10AM -0400, Shawn O. Pearce wrote:
> But at this point in git (and git-gui's) life I think it would
> be very worthwhile to devote an entire (new) chapter to git-gui,
> maybe as part of git 1.5.4/git-gui 0.9.0.  I think we're far too
> late in the 1.5.3 cycle to do it now.  I personally won't have the
> time to even try to rough draft something anytime soon, let alone
> let others copy-edit me before Juino releases 1.5.3.  :)
> 
> Being bundled with core git has brought git-gui a sizeable and
> growing userbase, and more and more users are discovering it
> each day.  We're now seeing it be translated into many different
> languages, and it is a somewhat core part of the MSYS port as many
> Windows users prefer to click in GUIs over type in cmd.exe terminal
> windows (can't say I blame them, cmd.exe is aweful!).
> 
> In other words I think git-gui should get roughly as much attention
> from the user manual as git-add/rm/mv/commit/checkout/branch get,
> as it offers the same feature set.  But it shouldn't distract from
> the command line part of the manual.
> 
> Maybe we should write parts of the manual in a "choose your own
> adventure style" and use different chapters for different paths.
> I think users can easily decide between the command line "i like to
> type" vs. the gui "i like to click" paths and focus their attention
> to the material they are most interested in.  :-)

Sure.

For now, though, I think it'd be simplest to start with an entirely
separate appendix.  And find a way to make links to that chapter are
prominently featured in Windows ports, as that sounds like an immediate
need.

And then later as git-gui progresses we can figure out how to integrate
it better.

--b.

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

[Steffen Prohaska]

On Aug 3, 2007, at 2:56 PM, J. Bruce Fields wrote:

> On Thu, Aug 02, 2007 at 11:01:01PM -0400, Shawn O. Pearce wrote:
>> Steffen, you seem to be more in-tune with the Mac UI standards
>> than I am.  Any suggestions on what I can do in git-gui to make
>> this feature more obvious to users?

 From time to time I have a look at the Apple Human Interface
Guidelines [1]. They contain large Apple specific sections but also
ideas of general interest.


>> I myself use a Mac OS X based PowerBook as my primary development
>> system, but I have to admit, I'm not the best GUI developer that has
>> ever walked on this planet.  Far far far from it.
>
> You're way ahead of me!
>
>> So I'd really love to do better.  But frankly I'm at a loss here
>> and just don't know what sort of change to make.
>
>> Side note: Someone recently asked me how to move individual files
>> to the left side of the UI (to stage them).  Apparently this person
>> had been using git-gui for months by just clicking "Add Existing"
>> (recently renamed to "Stage Changed").  It never occurred to the
>> user to try clicking the file's individual icons.  Or to select
>> the files they were interested in and look for a menu option that
>> might work on that selection.
>
> The one thing that struck me when I fired up git-gui was that it  
> wasn't
> obvious to me which things I should try clicking on.

I had the same experience. I didn't recognize that the document
icon left to a filename is actually a button with an action
attached to it. I thought it would be there just to distinguish
a file from a directory.

I'd tend to use kind of a push button instead of an icon to
indicate the action of adding a file to the index (staging).
Maybe an arrow facing left? And an arrow facing right to
unstage?


> For example: the buttons, drop-down menus, and check-boxes all cry out
> to be played with.  But the filenames in the lists at the top are less
> obvious, and it might never have occurred to me on my own to right- 
> click
> on the diff hunks at the bottom.  That just looks like passive  
> colorized
> text to me.
>
> I don't know what sort of user-interface conventions say "play with
> me!", though.  Random ideas:
>
> 	- maybe the cursor should change shape over the diff hunks (or
> 	  just the headers?)
> 	- maybe buttons, hunk headers, file names, etc., should all be
> 	  in the same color?
> 	- maybe the hunk headers could benefit from a little more
> 	  decoration?  I don't know how to do that without just making
> 	  the display look more cluttered, though.
> 	- maybe left-clicking on diff hunks should do something too?

In general it's always a good idea to make every action
accessible with only a single (left) mouse button. This
may seem ridiculous nowadays, but it really help to keep
things obvious. Right buttons and context menus have a
value for the experienced user to access things more
efficiently, but they should not be essential.

	Steffen

[1] http://developer.apple.com/documentation/UserExperience/ 
Conceptual/OSXHIGuidelines/index.html

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

[Steffen Prohaska]

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

>>
>> 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

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

[Brett Schwarz]

> 
> ----- Original Message ----
> From: Shawn O. Pearce <spearce@spearce.org>
> To: J. Bruce Fields <bfields@fieldses.org>
> Cc: Steffen Prohaska <prohaska@zib.de>; git@vger.kernel.org
> Sent: Friday, August 3, 2007 11:20:10 PM
> Subject: Re: [PATCH] user-manual: mention git gui citool (commit, amend)
> 
> "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > On Thu, Aug 02, 2007 at 11:04:59PM -0400, Shawn O. Pearce wrote:
> > > Online help?  In git-gui?  :-)
> > >
> > > We don't have an online help system yet.
> >
> > Fair enough.
> >
> > 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 haven't explored any in-Tk rendering options yet, been too busy
> with other projects.  Ideally I'd like to just render the asciidoc
> markup directly, but I don't think anyone has done an asciidoc
> viewer for Tk.  I can't imagine it would be that difficult to get
> some sort of parser working though...
> 
> 

So, I took a stab at this earlier today, and it is fairly straight forward. I have 
something that is semi working (I haven't tested all the scenarios yet), but 
the rest is just really filling in the blanks.

Question though: I was going to have a index tree on a side panel...but do
 you want this thing to only bring up the git-gui.txt file, and show the table 
of contents, or do you want all *.txt files in the index? Or .... ?

Thanks,
    --brett





       
____________________________________________________________________________________
Be a better Globetrotter. Get better travel answers from someone who knows. Yahoo! Answers - Check it out.
http://answers.yahoo.com/dir/?link=list&sid=396545469

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

[Shawn O. Pearce]

Brett Schwarz <brett_schwarz@yahoo.com> wrote:
> > From: Shawn O. Pearce <spearce@spearce.org>
> > 
> > I haven't explored any in-Tk rendering options yet, been too busy
> > with other projects.  Ideally I'd like to just render the asciidoc
> > markup directly, but I don't think anyone has done an asciidoc
> > viewer for Tk.  I can't imagine it would be that difficult to get
> > some sort of parser working though...
> > 
> > 
> 
> So, I took a stab at this earlier today, and it is fairly straight forward. I have 
> something that is semi working (I haven't tested all the scenarios yet), but 
> the rest is just really filling in the blanks.

Yea, I thought it would be really straight-forward.  The Tk text
widget is a really wonderful tool.  Makes these sorts things almost
write themselves...
 
> Question though: I was going to have a index tree on a side panel...but do
>  you want this thing to only bring up the git-gui.txt file, and show the table 
> of contents, or do you want all *.txt files in the index? Or .... ?

Yea, that's a good question.  I think I want all of that.  ;-)

I mean:

I'd like to be able to allow users to browse all of the Git manual
pages and the user manual, directly from within git-gui.  Then I
can setup a new subcommand `git gui help commit` to bring up the
git-commit manual page in this renderer (for example).  So in that
sense showing all of the manuals in an index is really useful.
This may make it easier for some users (e.g me!) as they don't have
to render the manuals, or rely upon the man/html branches from Junio.

I'd like to let users also browse the git user manual.  This is
a fairly large set of documentation, so the table of contents for
this thing is not just a list; a proper tree that one can browse
through is really nice.

And I'd like to start writing git-gui specific documentation,
and let users browse through that as well.

So whatever you can provide is great.  And you don't have to get
everything at once either; just showing single files would be a
great start.  Showing single files with the various section headers
in an "outline" view to the left would be even better.


I think one of the worst manuals we have is git-fast-import.
Its huge.  It uses a number of asciidoc features, and it has
a fairly large outline.  The user manual is actually a lot
more complex, but isn't a single file manual page.  ;-)

-- 
Shawn.