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

["Shawn O. Pearce" <spearce@spearce.org>]

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.