Re: [PATCH] Documentation/git-rebase.txt: fix -f description to match actual git behavior.

From: Sergey Organov <sorganov@gmail.com>
Date: Aug 13, 2014, 08:56 UTC
Message-ID: <87mwb8ahtb.fsf@osv.gnss.ru>
In-Reply-To: <xmqqzjf94f5n.fsf@gitster.dls.corp.google.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 15 quoted lines

> Junio C Hamano <gitster@pobox.com> writes:
>
>> So I think the reasoning (i.e. "is a descendant" is not quite right)
>> is correct, but the updated text is not quite right.  Changing it
>> further to "only the committer timestamps and identities would
>> change" is probably not an improvement, either.  "Force the rebase
>> that would otherwise be a no-op" may be a better phrasing that does
>> not risk going stale even if we update what are preserved and what
>> are modified in the future.
>>
>> Also I notice the sentence "Normally non-interactive...in such a
>> situation" is not helping the reader in this description very much.
>> I wonder if we should keep it if we are rewriting this paragraph.
>
> How about doing it this way, perhaps?

[...]

Show 12 quoted lines

>  -f::
>  --force-rebase::
> -	Force the rebase even if the current branch is a descendant
> -	of the commit you are rebasing onto.  Normally non-interactive rebase will
> -	exit with the message "Current branch is up to date" in such a
> -	situation.
> -	Incompatible with the --interactive option.
> +	Force a rebase even if the current branch is up-to-date and
> +	the command without `--force` would return without doing anything.
>  +
>  You may find this (or --no-ff with an interactive rebase) helpful after
>  reverting a topic branch merge, as this option recreates the topic branch with

It's OK with me, as in fact I think that there is no good explanation for current git behavior, and thus it's git behavior that should have been changed, not the documentation. I.e., git must not rebase anything when "Current branch is a descendant of the commit you are rebasing onto", unless -f is given. Simple, reasonable, straightforward.

The version you propose at least does not lie, so it's definiteley an improvement. However,

"Force the rebase when the command exits with "Current branch is up to date" message."

reads even more simple and clear for me.

-- 
Sergey.