From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 07 May 2012 17:06:06 GMT
Subject: Re: git-scm.com refresh
Message-ID: <7vipg77wg1.fsf@alter.siamese.dyndns.org>
In-Reply-To: <C0239E9A908644EAB06A52AE4A90F401@PhilipOakley>

"Philip Oakley" <philipoakley@iee.org> writes:

> From: "Junio C Hamano" <gitster@pobox.com> Sent: Sunday, May 06, 2012 2:39
>
>> "diff" pairs with "apply", and "format-patch" pairs with "am".
>>
>> I wouldn't mind adding "git patch" as a built-in synonym/alias for "git
>> apply", if you think that would make the above pairing more obvious.  Many
>> computer users know what "patch" does already even they have never used
>> any SCM.
>
> Part of the problem is that the `git diff` man page [1] doesn't actively
> tell the user that its result will be in a patch format, and that such a
> patch can be `apply`ed. There are only 5 uses of 'apply' buried in the body
> text, never as a command, as if they are special cases. There is a section
> on the -p option, again it feels like it is a special case.

Sounds like you spotted a good set of places in the documentation that
need to be updated.

> The normal case of `git diff` for most users is simply as an extended 'what
> changed' git status.

I think that use of "diff" is listed in "Inspection and Comparison"
section, and I fully agree and is happy to see "diff" there as well.  Of
course, I wouldn't suggest "apply" to go next to that use of "diff".

But what I have been discussing was the use of "diff" in the "Basic
Snapshotting" section.  I actually very often use "diff" paired with
"apply" for my own work, not when working to integrate others' work.  

Also I do not think anybody would use "apply" to accept patches (that is
what "am" is for), so listing it in "Email" section is doubly wrong.  If
for some reason the command Reference does not want to have "apply" next
to "diff" listed in "Basic Snapshotting", I do not think there is any
category on that page for the command to belong to.

The above two were the primary things that triggered my reaction.

When reshaping a multi-commit series, "git diff $rev1 $rev2 >P.diff"
followed by "git apply <P.diff" (either with or without editing P.diff in
between) is sometimes a more versatile and even more natural solution than
repeated use of "rebase -i" is, depending on what kind of reshaping
I want to do.

For example, after an exploratory development session, I often end up
with something like this (time flows from top to bottom):

	update A
        update D
        refactor and modify B
	update E
        refactor and modify C

and then I realize that the refactoring I needed to give to B and C are
the similar kind, and is better done as a single step early in the
series.  This will involve splitting two "refactor and modify" commits
into four, reorder and squash in different combinations.  It often is the
most convenient to

	git checkout ":/update A"
        git diff ":/update D" ":/refactor and modify B" | git apply
        git add -p ;# only keep the 'refactor' bit
        git checkout . ;# and lose the 'modify' part
        git diff ":/update E" ":/refactor and modify C" | git apply
        git add -p ;# only keep the 'refactor' bit
        git checkout . ;# and lose the 'modify' part
	git commit -c ':/refactor and modify C'

when rebuilding 'refactor B and C' on top of 'update A'.  Of course this
does not have to be "rebase" but picking only part of good infrastructure
change from totally unrelated branch.  A concrete example is the recent
index-v4 series started by a commit that borrowed a small part of older
jc/split-blob series to refactor a varint API, and the diff to apply pipe
with editing (because the API needed to be cleaned up for the index-v4
work) was how a part of change was extracted from older branch (later the
jc/split-blob was rewritten to base it on the updated varint API that
was cleaned up for the index-v4 series).

In such a workflow, the use of "diff" is very much "Basic snapshotting"
(which is the category head I was referring to).  It is used as a mechaism
to take a snapshot, and not as a measure for "Inspection and Comparison".

And the way to replay that basic snapshot to the working tree is "git
apply".  Without the matching pair, "git diff" does not serve well as a
"Basic snapshotting" feature.

I do not think Scott is ignorant of or unsympathetic to such a use case
(after all, he mentioned use of GNU patch on "git diff" output, so he must
use "take a diff to stash away some change, then replay it to the working
tree" workflow, even if much less often than I do.  Perhaps he personally
uses it not so often and its usefulness escaped him).

It is a different topic if it makes sense to enhance "rebase -i" to
support "split two, shuffle and squash in a different way".  I do not
think of a good UI for such an operation offhand.