Re: [PATCH 3/3] branch documentation: new autosetupmerge option "simple"

[Junio C Hamano <gitster@pobox.com>]

"Tao Klerks via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Tao Klerks <tao@klerks.biz>
>
> Updating the branch and config documentation to reflect
> the new "simple" option to branch.autosetupmerge.

Documentation/Submittingpatches[[describe-changes]].

But it would be moot; these changes are better done as part of [1/3]
and in that case, updating the documentation (or testing the desired
behaviour, for that matter) is not something we need to justify
separately.  It is something we must done as part of the change.

> diff --git a/Documentation/config/branch.txt b/Documentation/config/branch.txt
> index 1e0c7af014b..7b4e5ca5b74 100644
> --- a/Documentation/config/branch.txt
> +++ b/Documentation/config/branch.txt
> @@ -9,7 +9,9 @@ branch.autoSetupMerge::
>  	automatic setup is done when the starting point is either a
>  	local branch or remote-tracking branch; `inherit` -- if the starting point
>  	has a tracking configuration, it is copied to the new
> -	branch. This option defaults to true.
> +	branch; `simple` -- automatic setup is done when the starting point is

It may be clearer to say "done only when".  I dunno.

> +	a remote-tracking branch and the new branch has the same name as the
> +	remote branch. This option defaults to true.

> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index c8b4f9ce3c7..f99d6a6b008 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -227,7 +227,9 @@ want `git switch`, `git checkout` and `git branch` to always behave as if `--no-
>  were given. Set it to `always` if you want this behavior when the
>  start-point is either a local or remote-tracking branch. Set it to
>  `inherit` if you want to copy the tracking configuration from the
> -branch point.
> +branch point. Set it to `simple` if you want this behavior only when
> +the start-point is a remote branch and the new branch has the same name
> +as the remote branch.

The existing "if you want this behaviour when" is already awkward.
What it means is that only those who want to use the "start-point"
itself as the upstream whether the start-point is local or
remote-tracking,can use "always" and does not get hurt.

But using the phrase for "simple" makes it even worse, as the
condition that the tracking behaviour kicks in is even narrower.  If
you know that start-point is not a remote-tracking branch (by the
way, do not say "remote branch" when you mean "remote-tracking
brnach"), or its name is not the same as the local branch, you just
do not pass --track=simple from the command line.  Strike everything
after "Set it to `simple`" and replace with something like

    `--track=simple` sets up the upstream information only when the
    start-point is a remote-tracking branch and ...

perhaps?

Thanks.