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 ...
[ message continues ]

Actually `git citool` is an alias for `git gui citool`.  Because the

But this note is also really useful.  So maybe talking about the

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.

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

-- 
Shawn.
-

[ message continues ]

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


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

[ message continues ]

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

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

	Steffen

-

[ message continues ]

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

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

[ message continues ]

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



-

[ message continues ]

Sounds good to me.  Somebody do that!

--b.
-

[ message continues ]

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

-

[ message continues ]

Hi,


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

-

[ message continues ]

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
-

[ message continues ]

Hi,


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

Ciao,
Dscho

-

[ message continues ]

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
-

[ message continues ]

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

-

[ message continues ]

Him


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

-

[ message continues ]

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

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


-

[ message continues ]

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
-

[ message continues ]

Hi,


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

Ciao,
Dscho

-

[ message continues ]

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

[ message continues ]

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

[ message continues ]

Hi,


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

-

[ message continues ]

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
 ...
[ message continues ]

m
[ message continues ]

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

[ message continues ]

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

[ message continues ]

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

[ message continues ]

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

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

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

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

[ message continues ]

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

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

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

-

[ message continues ]

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.




-

[ message continues ]

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

[ message continues ]

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

[ message continues ]

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

[ message continues ]

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
-

[ message continues ]

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

[ message continues ]

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
-

[ message continues ]