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

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 12, 2014, 19:47 UTC
Message-ID: <xmqq4mxh5w34.fsf@gitster.dls.corp.google.com>
In-Reply-To: <87bnrq22uf.fsf@osv.gnss.ru>

Sergey Organov <sorganov@gmail.com> writes:

> Previous description of -f option was wrong as "git rebase" does not
> require -f to perform rebase when "current branch is a descendant of
> the commit you are rebasing onto", provided commit(s) to be rebased
> contain merge(s).

Both the above and the updated documentation are a bit hard to read for me, so let me disect what you are and you are not saying to see if I understood them correctly:

 - The plain-vanilla "git rebase" that flattens the history will be
   a no-op *only* when the current tip is a linear descendant of the
   "onto" commit without any merge in between.

 - Merge-preserving form of "git rebase -m/-p" is a no-op when the
   current tip is a descendant of the "onto" commit.

 - "rebase -f" is a way to force rebase when it would otherwise be a
   no-op.

 - When you force a rebase that would otherwise be a no-op, only the
   timestamps would change.

I think you are right that 'current branch is a descendant of the "onto" commit' is not necessarily equal to 'rebase that would otherwise be a no-op'. I am not sure if a 'rebase that would otherwise be a no-op' is equal to 'only timestamp would change', though. What happens if you do this, for example?

    $ GIT_COMMITTER_NAME='Somebody Else' git commit
    $ git rebase --force --onto HEAD^ HEAD^ HEAD^0

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.

Thanks.

Show 23 quoted lines

> Signed-off-by: Sergey Organov <sorganov@gmail.com>
> ---
>  Documentation/git-rebase.txt | 7 +++----
>  1 file changed, 3 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index 2a93c64..62dac31 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -316,10 +316,9 @@ which makes little sense.
>  
>  -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.
> +	Force the rebase even if the result will only change commit
> +	timestamps. Normally non-interactive rebase will exit with the
> +	message "Current branch is up to date" in such a situation.
>  	Incompatible with the --interactive option.
>  +
>  You may find this (or --no-ff with an interactive rebase) helpful after