Re: git-scm.com refresh

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

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

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.