Re: [PATCH] branch doc: remove --set-upstream from synopsis

From: Martin Ågren <martin.agren@gmail.com>
Date: Nov 16, 2017, 10:49 UTC
Message-ID: <CAN0heSpUm=U7aGVtRoUoGZCvNsOZ04wLqTOx8kMvZEa8GQUiLQ@mail.gmail.com>
In-Reply-To: <20171116074643.19614-1-tmz@pobox.com>

On 16 November 2017 at 08:46, Todd Zullinger <tmz@pobox.com> wrote:

Show 17 quoted lines

> Support for the --set-upstream option was removed in 52668846ea
> (builtin/branch: stop supporting the "--set-upstream" option,
> 2017-08-17), after a long deprecation period.
>
> Remove the option from the command synopsis for consistency.  Replace
> another reference to it in the description of `--delete` with
> `--set-upstream-to`.
>
> Signed-off-by: Todd Zullinger <tmz@pobox.com>
> ---
>
> I noticed that --set-upstream was still in the synopsis for git branch.  I
> don't think it was left there intentionally.  I looked through the thread where
> support for the option was removed and didn't notice any comments suggesting
> otherwise[1].  With luck, I didn't miss the obvious while reading the thread.
>
> [1] https://public-inbox.org/git/20170807143938.5127-1-kaarticsivaraam91196@gmail.com/

Actually, the first version of the series did remove it from the synopsis [2]. That hunk was later dropped. Kaartic mentioned it [3] and I thought out loud about it [4].

I get the same initial thought now as then: It's a bit odd that we pique the interest of the reader, but that when they try it out or read up on it, we say "nope, this is not what you are looking for".

Show 10 quoted lines

> diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
> index d6587c5e96..159ca388f1 100644
> --- a/Documentation/git-branch.txt
> +++ b/Documentation/git-branch.txt
> @@ -14,7 +14,7 @@ SYNOPSIS
>         [(--merged | --no-merged) [<commit>]]
>         [--contains [<commit]] [--no-contains [<commit>]]
>         [--points-at <object>] [--format=<format>] [<pattern>...]
> -'git branch' [--set-upstream | --track | --no-track] [-l] [-f] <branchname> [<start-point>]
> +'git branch' [--track | --no-track] [-l] [-f] <branchname> [<start-point>]

Personally, I think this is an improvement.

Show 9 quoted lines

>  'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>]
>  'git branch' --unset-upstream [<branchname>]
>  'git branch' (-m | -M) [<oldbranch>] <newbranch>
> @@ -86,7 +86,7 @@ OPTIONS
>  --delete::
>         Delete a branch. The branch must be fully merged in its
>         upstream branch, or in `HEAD` if no upstream was set with
> -       `--track` or `--set-upstream`.
> +       `--track` or `--set-upstream-to`.

Good catch.

Martin

[2] https://public-inbox.org/git/20170807143938.5127-2-kaarticsivaraam91196@gmail.com/

[3] https://public-inbox.org/git/20170817025425.6647-2-kaarticsivaraam91196@gmail.com/

[4] https://public-inbox.org/git/CAN0heSquaXk421sR6Ry59C+er8n26nC93=3KG1wD0xNXZkuiGw@mail.gmail.com/