Re: [PATCH v1 3/3] doc: rebase: clarify fixup! fixup! constraint

["Philip Oakley" <philipoakley@iee.org>]

From: "Junio C Hamano" <gitster@pobox.com>
> Philip Oakley <philipoakley@iee.org> writes:
>
>> 22c5b13 (rebase -i: handle fixup! fixup! in --autosquash, 2013-06-27)
>
> That's a noun that names a commit object.  What about it?

It's the commit that introduced the original change that's being clarified. 
Is a paragraph needed or simply "Ref commit: .."

>
>> I certainly misunderstood what this meant. It sounded like only one 
>> fixup! was
>> allowed per commit (i.e. one mistake) - fixing two mistakes wouldn't be
>> allowed. Hindsight is a wonderful thing.
>
> I think this is about

Yes, but the original wording didn't make me think that.

>
> git commit -m foo
> ... some other commits
>        git commit -m 'fixup! foo'
> ... even more other commits
>        git commit -m 'fixup! fixup! foo'
>
> The last one is technically a fixup of the second one, but as long
> as the second one is to be applied _and_ the last one comes after
> the second one, we could say that both of them are fix-ups for the
> very first one.  And that is what the original text says.

No. To me it said "You can only have one fixup (commit) for any given 
commit". So that's one original, and one fixup. After that the autosquash 
would leave the remaining fixup commits in their original positions in the 
commit sequence. Hence the patch.

>
> I have a feeling that if the editor session to edit the todo drops
> the second one and leaves this:
>
> pick foo
>        fixup fixup! fixup! foo
>
> the command _should_ notice that the second one that is required to
> apply the last one is gone and error out, but probably the code does
> not do so, and if that is the case, I think "they fix the very first
> commit that invited these fixups" is a more reasonable description
> than the more technically stringent "fixup! fixup! is to fix what
> the fixup! did", which is not what the code implements.
>
>> Also, does 'earliest commit requiring fixup/squash' fully convey that
>> its the one to fix.
>
> I cannot tell if that a question or a statement?

It's a question. In your prior para you offer "they fix the very first
> commit that invited these fixups" as an alternate.
It's when a users mental model is that they got their first fixup wrong and 
it's that fixup they are correcting, and later they add different fixups to 
the orignal that it all gets hairy.
(diffs must have the right sequence, while snapshots don't care - so if we 
keep the diff sequence, we don't care about the user's mental model as the 
end results are the same).

The writeup needs to cope with the mental model rather than the end result.

It maybe that the whole 'fixup/squash' capability should be brought out as a 
small separate section to give space to these points and the user 
understanding.
>
>> ---
>>  Documentation/git-rebase.txt | 6 +++---
>>  1 file changed, 3 insertions(+), 3 deletions(-)
>>
>> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
>> index 66b789a..91eb107 100644
>> --- a/Documentation/git-rebase.txt
>> +++ b/Documentation/git-rebase.txt
>> @@ -425,9 +425,9 @@ without an explicit `--interactive`.
>>  automatically modify the todo list of rebase -i
>>  so that the commit marked for squashing comes right after the
>>  commit to be modified, and change the action of the moved
>> - commit from `pick` to `squash` (or `fixup`).  Ignores subsequent
>> - "fixup! " or "squash! " after the first, in case you referred to an
>> - earlier fixup/squash with `git commit --fixup/--squash`.
>> + commit from `pick` to `squash` (or `fixup`).  Commits with repeated
>> + "fixup! " or "squash! " in the subject line are considered to refer
>> + to the earliest commit requiring fixup/squash.
>>  +
>>  This option is only valid when the '--interactive' option is used.
>>  +
>