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

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

[PATCH v2] 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 briefly mentioned in the user-manual.

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

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 0071cd0..6865d21 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1079,6 +1079,17 @@ $ 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, which lets you add files (use menu
+'Commit > Stage to Commit') or individually diff hunks (use
+'Stage Hunk For Commit' in the context menu of the diff view)
+to the index.
+
 [[creating-good-commit-messages]]
 Creating good commit messages
 -----------------------------
@@ -2482,6 +2493,10 @@ applying them (possibly in a different order) to mywork-new using
 cherry-pick, and possibly modifying them as you go using commit
 --amend.
 
+git gui is especially useful to rework commits as it lets you
+selectively add single diff hunks to the index (use
+'Stage Hunk For Commit' in the context menu of the diff view).
+
 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.151.g8d6306

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

[Johannes Schindelin]

Hi,

On Sun, 5 Aug 2007, Steffen Prohaska wrote:

> git gui is especially useful because it allows to select diff hunks.

You should give a _big_ _fat_ _red_ warning there.

If you selectively commit diff hunks, you _never_ tested what you 
committed.

That is the reason we're not advertising git add -i more actively.

Ciao,
Dscho

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

[Steffen Prohaska]

On Aug 5, 2007, at 3:58 PM, Johannes Schindelin wrote:

> Hi,
>
> On Sun, 5 Aug 2007, Steffen Prohaska wrote:
>
>> git gui is especially useful because it allows to select diff hunks.
>
> You should give a _big_ _fat_ _red_ warning there.
>
> If you selectively commit diff hunks, you _never_ tested what you
> committed.
>
> That is the reason we're not advertising git add -i more actively.

Hmm... If you do 'git cherry-pick' or 'git rebase' you also did
not test what you committed. Should we advertise them less
actively as well?

But I see your point. Selecting diff hunks tends to be more fine
grained than cherry-picking. But this depends on the details of
what you're doing. I don't think a general warning is appropriate.

	Steffen

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

[Johannes Schindelin]

Hi,

On Sun, 5 Aug 2007, Steffen Prohaska wrote:

> On Aug 5, 2007, at 3:58 PM, Johannes Schindelin wrote:
> 
> > Hi,
> > 
> > On Sun, 5 Aug 2007, Steffen Prohaska wrote:
> > 
> > > git gui is especially useful because it allows to select diff hunks.
> > 
> > You should give a _big_ _fat_ _red_ warning there.
> > 
> > If you selectively commit diff hunks, you _never_ tested what you
> > committed.
> > 
> > That is the reason we're not advertising git add -i more actively.
> 
> Hmm... If you do 'git cherry-pick' or 'git rebase' you also did
> not test what you committed. Should we advertise them less
> actively as well?

But you have that state in your working tree!  Big difference there!

Ciao,
Dscho

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

[David Kastrup]

Steffen Prohaska <prohaska@zib.de> writes:

> On Aug 5, 2007, at 3:58 PM, Johannes Schindelin wrote:
>
>> Hi,
>>
>> On Sun, 5 Aug 2007, Steffen Prohaska wrote:
>>
>>> git gui is especially useful because it allows to select diff hunks.
>>
>> You should give a _big_ _fat_ _red_ warning there.
>>
>> If you selectively commit diff hunks, you _never_ tested what you
>> committed.
>>
>> That is the reason we're not advertising git add -i more actively.
>
> Hmm... If you do 'git cherry-pick' or 'git rebase' you also did
> not test what you committed. Should we advertise them less
> actively as well?

Selectively committing diff hunks also means that a subsequent rebase
-i or git-cherry will have to reconsider the same commit as it has
only been incompletely applied.

So it can mean more work later.  Also one would in general have to
edit the commit message (if it describes everything that has been
done).

There are simply consequences for the workflow if you do things
right.  Whether they are worth a "big fat red warning" is one
question, but mentioning them is probably not amiss.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

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

[Steffen Prohaska]

On Aug 5, 2007, at 5:03 PM, David Kastrup wrote:

> Steffen Prohaska <prohaska@zib.de> writes:
>
>> On Aug 5, 2007, at 3:58 PM, Johannes Schindelin wrote:
>>
>>> Hi,
>>>
>>> On Sun, 5 Aug 2007, Steffen Prohaska wrote:
>>>
>>>> git gui is especially useful because it allows to select diff  
>>>> hunks.
>>>
>>> You should give a _big_ _fat_ _red_ warning there.
>>>
>>> If you selectively commit diff hunks, you _never_ tested what you
>>> committed.
>>>
>>> That is the reason we're not advertising git add -i more actively.
>>
>> Hmm... If you do 'git cherry-pick' or 'git rebase' you also did
>> not test what you committed. Should we advertise them less
>> actively as well?
>
> Selectively committing diff hunks also means that a subsequent rebase
> -i or git-cherry will have to reconsider the same commit as it has
> only been incompletely applied.
>
> So it can mean more work later.  Also one would in general have to
> edit the commit message (if it describes everything that has been
> done).
>
> There are simply consequences for the workflow if you do things
> right.  Whether they are worth a "big fat red warning" is one
> question, but mentioning them is probably not amiss.

I found it quite useful to be able to commit diff chunks selectively.
I started editing diffs as described in [1] but actually it turned
out to be easier for me to use git gui. I'm speaking unified diff
probably less fluently than Linus does.

My note about using git gui to select diff hunks is added to the
section 'Reordering or selecting from a patch series', which is in
my opinion the right section.

But apparently there's some dispute about usefulness of my comment on
cherry-picking. Maybe a separate section on rewriting changes would
be useful, which I do not have the time to start right now.

Junio, maybe you want to take only the first part of my patch?

	Steffen

[1] http://thread.gmane.org/gmane.comp.version-control.git/46733

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

[Johannes Schindelin]

Him

On Sun, 5 Aug 2007, Steffen Prohaska wrote:

> I found it quite useful to be able to commit diff chunks selectively.

But how do you make sure that it works as expected?  I.e. when you commit 
a hunk using, say, variable "rule_the_world", and by mistake (happen to me 
all the time, maybe to you, too?) forgot to select the hunk which declares 
that variable, maybe because it is hidden in a forest of other variables?

I _try_ to test commits by my eyes, by compiling, and by running the 
version I'll commit.  (Okay, sometimes I run the test _after_ committing, 
but then I test to see if I have to amend something.)

Ciao,
Dscho

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

[Steffen Prohaska]

On Aug 6, 2007, at 2:22 AM, Johannes Schindelin wrote:

> On Sun, 5 Aug 2007, Steffen Prohaska wrote:
>
>> I found it quite useful to be able to commit diff chunks selectively.
>
> But how do you make sure that it works as expected?  I.e. when you  
> commit
> a hunk using, say, variable "rule_the_world", and by mistake  
> (happen to me
> all the time, maybe to you, too?) forgot to select the hunk which  
> declares
> that variable, maybe because it is hidden in a forest of other  
> variables?

In various ways, the details depend on what I'm doing. Here are three
examples.

1) I push the commit to a faster machine to compile it there and  
continue
working on the next commit (a complete build of the software package  
that
I'm mostly working on takes approximately 30 min on our fastest  
machines. I
can't wait for this before I continue working. Luckily a complete  
compile is
rarely needed).

2) I don't care about a single commit. I only care about the result of a
series of commits. I need to check on multiple architectures anyway  
and can't
thoroughly test what I'm doing right now. Regularly gcc and Microsoft
compilers disagree on warnings.

3) I push a series of commits to my scratch space and wait one night  
for the
automated builds to complete on all architectures.

> I _try_ to test commits by my eyes, by compiling, and by running the
> version I'll commit.  (Okay, sometimes I run the test _after_  
> committing,
> but then I test to see if I have to amend something.)

Option (1) is probably the only solution that fulfills your  
requirement that
every single commit should compile and work. This is a perfect  
approach but
sometimes take too much time for me.

	Steffen

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

[Steven Grimm]

Johannes Schindelin wrote:
> But how do you make sure that it works as expected?  I.e. when you commit 
> a hunk using, say, variable "rule_the_world", and by mistake (happen to me 
> all the time, maybe to you, too?) forgot to select the hunk which declares 
> that variable, maybe because it is hidden in a forest of other variables?
>   

For cases like that, sure, partial commits are dangerous. On the other 
hand, I've sometimes done partial commits for things like correcting 
erroneous comments in code I'm working on, where there is no functional 
change whatsoever in the hunk I'm committing and where I want to isolate 
the corrections from the functional changes I *am* working on.

Also, when I'm working on a topic branch in my local sandbox I like to 
do lots of work-in-progress commits. I usually do those based on the 
granularity of my mental model of what I'm working on, and I have no 
expectation whatsoever that any particular percentage of them represent 
working code or even code that compiles. Sometimes I do partial commits 
in that situation too: I make a change to some function in a file that 
I'm editing elsewhere, and commit just that hunk with a commit log 
message reminding me of why I made the change. Those commits are not 
intended for public consumption; they're just to help me keep track of 
my own work. Once everything is in a working state, I do a squash merge 
or a bunch of cherry-pick -n invocations to build some revisions to 
publish to the outside world, and *then* I am in "each commit must 
represent a non-broken state" mode.

The great thing about git (well, *one* of the great things) is that it 
unifies those two workflows in one system. With, say, svn, the "lots of 
little checkpoints of my work in progress" part of that is awkward at 
best, because it's very much oriented around an "if the version control 
system knows about a change, it is by definition published to the 
outside world" model.

So I guess my point, after all that, is just that assumptions that are 
valid in the context of one workflow are not necessarily as valid in 
others, and that even in a particular context, not all changes are 
created equal.

-Steve

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

[Johannes Schindelin]

Hi,

On Mon, 6 Aug 2007, Steven Grimm wrote:
>
> [I pointed out how dangerous committing hunks selectively can be]
>
> So I guess my point, after all that, is just that assumptions that are 
> valid in the context of one workflow are not necessarily as valid in 
> others, and that even in a particular context, not all changes are 
> created equal.

Right.  But I think a warning _is_ needed.  So that everybody considers if 
it is safe in _her_ workflow.

Ciao,
Dscho

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

[J. Bruce Fields]

On Sun, Aug 05, 2007 at 02:58:11PM +0100, Johannes Schindelin wrote:
> On Sun, 5 Aug 2007, Steffen Prohaska wrote:
> 
> > git gui is especially useful because it allows to select diff hunks.
> 
> You should give a _big_ _fat_ _red_ warning there.
> 
> If you selectively commit diff hunks, you _never_ tested what you 
> committed.

A big warning would be out of place in what is for now just an isolated
sentence in two different places.  But I agree with you that this would
be worth mentioning in any eventual full-fledged git-gui tutorial.

--b.

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

[J. Bruce Fields]

On Sun, Aug 05, 2007 at 06:22:13PM -0400, J. Bruce Fields wrote:
> On Sun, Aug 05, 2007 at 02:58:11PM +0100, Johannes Schindelin wrote:
> > On Sun, 5 Aug 2007, Steffen Prohaska wrote:
> > 
> > > git gui is especially useful because it allows to select diff hunks.
> > 
> > You should give a _big_ _fat_ _red_ warning there.
> > 
> > If you selectively commit diff hunks, you _never_ tested what you 
> > committed.
> 
> A big warning would be out of place in what is for now just an isolated
> sentence in two different places.  But I agree with you that this would
> be worth mentioning in any eventual full-fledged git-gui tutorial.

(Oh, and my own attempt, along with a couple other minor manual updates,
is in the master branch at

	git://linux-nfs.org/~bfields/git.git master

Feel free to take that whenever, if it looks OK, Junio.)

--b.

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

[Johannes Schindelin]

Hi,

On Sun, 5 Aug 2007, J. Bruce Fields wrote:

> On Sun, Aug 05, 2007 at 02:58:11PM +0100, Johannes Schindelin wrote:
> > On Sun, 5 Aug 2007, Steffen Prohaska wrote:
> > 
> > > git gui is especially useful because it allows to select diff hunks.
> > 
> > You should give a _big_ _fat_ _red_ warning there.
> > 
> > If you selectively commit diff hunks, you _never_ tested what you 
> > committed.
> 
> A big warning would be out of place in what is for now just an isolated
> sentence in two different places.  But I agree with you that this would
> be worth mentioning in any eventual full-fledged git-gui tutorial.

Unfortunately, I am really wasted by this weekend's efforts to bring 
msysgit.git along... could you be so kind as to cut&paste the relevant 
section in a reply to me, so I do not have to search for myself?

I would not normally ask for such a favour; it is relatively easy to go on 
a search with Git, but I do have only 8 hours of sleep in the last 60 
hours under my saddle...

Ciao,
Dscho

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

[J. Bruce Fields]

On Mon, Aug 06, 2007 at 01:26:21AM +0100, Johannes Schindelin wrote:
> On Sun, 5 Aug 2007, J. Bruce Fields wrote:
> > A big warning would be out of place in what is for now just an isolated
> > sentence in two different places.  But I agree with you that this would
> > be worth mentioning in any eventual full-fledged git-gui tutorial.
> 
> Unfortunately, I am really wasted by this weekend's efforts to bring 
> msysgit.git along... could you be so kind as to cut&paste the relevant 
> section in a reply to me, so I do not have to search for myself?

Sure; appended.  This isn't that different from Steffen's proposal.

> I would not normally ask for such a favour; it is relatively easy to go on 
> a search with Git, but I do have only 8 hours of sleep in the last 60 
> hours under my saddle...

Hm.  On the other hand, maybe we should just be refusing to feed your
addiction till you get some sleep.

I wanna keep this short for now, so if we really think we shouldn't
mention of the hunk-selection thing without a warning, I'd rather just
omit mention of it, and go for something like: "You can also use
gitlink:git-gui[1] to create commits and view changes in the index and
working tree", and drop the second hunk.  Whatever.

--b.

>From 407c0c87e15b3cf60347f4fc0bcdb4d239de4163 Mon Sep 17 00:00:00 2001
From: J. Bruce Fields <bfields@pig.linuxdev.us.dell.com>
Date: Sun, 5 Aug 2007 18:12:37 -0400
Subject: [PATCH] user-manual: mention git-gui

The git gui project seems to be still in early stages, but at a point
where it's worth mentioning as an alternative way of creating commits.

One feature of interest is the ability to manipulate individual diff
hunks.  However, people have found that feature not to be easily
discoverable from the user-interface.  Pending some ui improvements, a
parenthetical hint here may help.

(Thanks to Steffen Prohask and Junio Hamano for suggesting the
language.)

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
---
 Documentation/user-manual.txt |   11 +++++++++--
 1 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 9efe85c..f89952a 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1079,6 +1079,11 @@ $ git diff HEAD	    # difference between HEAD and working tree; what
 $ git status	    # a brief per-file summary of the above.
 -------------------------------------------------
 
+You can also use gitlink:git-gui[1] to create commits, view changes in
+the index and the working tree files, and individually select diff hunks
+for inclusion in the index (by right-clicking on the diff hunk and
+choosing "Stage Hunk For Commit").
+
 [[creating-good-commit-messages]]
 Creating good commit messages
 -----------------------------
@@ -2506,8 +2511,10 @@ $ 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.
+cherry-pick, and possibly modifying them as you go using commit --amend.
+The git-gui[1] command may also help as it allows you to individually
+select diff hunks for inclusion in the index (by right-clicking on the
+diff hunk and choosing "Stage Hunk for Commit").
 
 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.GIT

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

[Robin Rosenberg]

måndag 06 augusti 2007 skrev J. Bruce Fields:
> On Mon, Aug 06, 2007 at 01:26:21AM +0100, Johannes Schindelin wrote:
> > On Sun, 5 Aug 2007, J. Bruce Fields wrote:
> > > A big warning would be out of place in what is for now just an isolated
> > > sentence in two different places.  But I agree with you that this would
> > > be worth mentioning in any eventual full-fledged git-gui tutorial.
> > 
> > Unfortunately, I am really wasted by this weekend's efforts to bring 
> > msysgit.git along... could you be so kind as to cut&paste the relevant 
> > section in a reply to me, so I do not have to search for myself?
> 
> Sure; appended.  This isn't that different from Steffen's proposal.
> 
> > I would not normally ask for such a favour; it is relatively easy to go on 
> > a search with Git, but I do have only 8 hours of sleep in the last 60 
> > hours under my saddle...
> 
> Hm.  On the other hand, maybe we should just be refusing to feed your
> addiction till you get some sleep.
> 
> I wanna keep this short for now, so if we really think we shouldn't
> mention of the hunk-selection thing without a warning, I'd rather just
> omit mention of it, and go for something like: "You can also use
> gitlink:git-gui[1] to create commits and view changes in the index and
> working tree", and drop the second hunk.  Whatever.

Who reads manuals for GUI's? Rougly nobody, unless the user needs the gui 
badly AND the GUI sucks badly. Manuals for GUI's are mostly tick-in-the-box 
documentation (which is the probably reason most GUI documentation suck too).

Uncommon/dangerous features should generally be harder to find, but can you 
can also use the common pattern of popping a dialog explaining the dangers 
and forcing the user to click away the box. Of course there should be a 
checkbox in the dialog "[X] Void warranty and don't bother me with this 
question anymore."

Nevertheless the dangers should be explained somewhere, maybe in the git user 
manual. I believe most people will learn from experience.

-- robin

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

[J. Bruce Fields]

On Mon, Aug 06, 2007 at 09:36:49PM +0200, Robin Rosenberg wrote:
> Who reads manuals for GUI's? Rougly nobody, unless the user needs the gui 
> badly AND the GUI sucks badly. Manuals for GUI's are mostly tick-in-the-box 
> documentation (which is the probably reason most GUI documentation suck too).

I tend to agree.  But the goal for now isn't to provide complete
documentation, it's just to briefly point out the existence of this tool
and what it does.

I haven't used it myself other than just to experiment a bit, but my
impression from the people involved is that they still consider it a bit
young, but that they think it's useful and that they'd benefit from more
people trying it out.

--b.

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)

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

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

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

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

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

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

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