From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 29 Sep 2014 16:26:27 GMT
Subject: Re: [PATCH v2] Documentation/git-rebase.txt: discuss --fork-point assumption of vanilla "git rebase" in DESCRIPTION.
Message-ID: <xmqq7g0m75qk.fsf@gitster.dls.corp.google.com>
In-Reply-To: <87k34mn0ht.fsf@osv.gnss.ru>

Sergey Organov <sorganov@gmail.com> writes:

> Vanilla "git rebase" defaults to --fork-point that in some cases
> makes behavior very different from "git rebase <upstream>",
> where --no-fork-point is assumed. This fact was not mentioned in
> the DESCRIPTION section of the manual page, even though the case of
> omitted <upstream> was otherwise discussed. That in turn made actual
> behavior of vanilla "git rebase" hardly discoverable.
>
> While we are at it, clarify the --fork-point description itself as well.
>
> Signed-off-by: Sergey Organov <sorganov@gmail.com>
> ---
> As asked by Junio C Hamano <gitster@pobox.com>, the newly introduced
> 'fork_point' term has been described.
>

I suspect "will be used as a fallback" might be easier to understand
what is going on instead of "will be used instead", but other than
that, the new explanation of what fork-point is is a very welcome
update, I think.

> diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt
> index 4138554..2e6f125 100644
> --- a/Documentation/git-rebase.txt
> +++ b/Documentation/git-rebase.txt
> @@ -21,15 +21,17 @@ If <branch> is specified, 'git rebase' will perform an automatic
>  it remains on the current branch.
>  
>  If <upstream> is not specified, the upstream configured in
> +branch.<name>.remote and branch.<name>.merge options will be used (see
> +linkgit:git-config[1] for details) and the `--fork-point` option is
> +assumed.  If you are currently not on any branch or if the current
> +branch does not have a configured upstream, the rebase will abort.
>  
>  All changes made by commits in the current branch but that are not
>  in <upstream> are saved to a temporary area.  This is the same set
> +of commits that would be shown by `git log <upstream>..HEAD`; or by
> +`git log 'fork_point'..HEAD`, if --fork-point is either specified or
> +assumed (see --fork-point description below); or by `git log HEAD`, if
> +--root is specified.

It is easier to read with "is either specified or assumed" shortened
to "is active", I think, because that is the word you use to explain
how the commit is computed for --fork-point processing.

> @@ -327,13 +329,18 @@
> link:howto/revert-a-faulty-merge.html[revert-a-faulty-merge How-To]
> for details)
>  
>  --fork-point::
>  --no-fork-point::
> +	Use reflog to find a better common ancestor between <upstream>
> +	and <branch> when calculating which commits have been
> +	introduced by <branch>. 
>  +
> +When --fork-point is active, 'fork_point' will be used instead of
> +<upstream> to calculate the set of commits to rebase, where
> +'fork_point' is the result of `git merge-base --fork-point <upstream>
> +<branch>` command (see linkgit:git-merge-base[1]).  If 'fork_point'
> +ends up being empty, the <upstream> will be used instead.
> ++
> +If either <upstream> or --root is given on the command line, then the
> +default is `--no-fork-point`, otherwise the default is `--fork-point`.
>  
>  --ignore-whitespace::
>  --whitespace=<option>::


The patch failed to apply

Applying: Documentation/git-rebase.txt: discuss --fork-point assumption of vanilla "git rebase" in DESCRIPTION.
fatal: corrupt patch at line 38

but the fix-up is trivial, so no need to resend.

Thanks.