[1.8.0] Change branch --set-uptream to take an argument

Proposal:

Currently it is very easy to misinvoke --set-upstream if you assume it takes an argument:

e.g.

  (master)$ git branch --set-upstream origin/master
  Branch origin/master set up to track local branch master.

In order to make its usage unambiguous, and to allow it to be used w/o specifying the current branch, require it to take an argument like so:

  (master)$ git branch --set-upstream=origin/master

(I've misinvoked it so often, I've had to train myself to always invoke it this way: git branch master --set-upstream origin/master)

Risks:

Hands which have become trained to use it as it currently is, scripts, etc.

Migration plan:

Introduce the new syntax to the man page and git branch for 1.7.x and emit a warning whenever the current syntax is used. In 1.8, break the current syntax.

(Though I'm not sure whether the options parser allows for both --set-upstream and --set-upstream=<arg>)

j.

Jay Soffian <jaysoffian@gmail.com> writes:

Your proposal sounds interesting, but I'd like to see something more global: right now, some commands take a --track option and other take a --set-upstream. In short, I'd like to see this --track deprecated (since it's not actually about remote-tracking ...).

There are already many instances of this. When <arg> is mandatory, you can write either --option <arg> or --option=<arg> (like "git log --grep pattern" Vs "git log --grep=pattern"), and when <arg> is optional, you can write either --option alone, or --option=<arg> (like "git diff --color-words" and "git diff --color-words=.").

On Tue, Feb 1, 2011 at 4:01 AM, Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> wrote:

There are a few things at work here. --track/--no-track are used to override the branch.autosetupmerge configuration and are supported by checkout and branch. --set-upstream is only supported by branch, and is subtly different from --track.

There is also branch.autosetuprebase, for which there is no command-line option to override.

These options/configs control how branch.<name>.{merge,remote,rebase} are set. --track/--no-track only take effect when the branch is created. --set-upstream can be used when the branch is created, or after the fact.

(Aside, the names of the config params are starting to look sub-optimal, but it's probably not worth the pain of changing them.)

I suppose a more comprehensive proposal looks like this:

1. Deprecate --track and --no-track (remove from documentation and
usage). I wonder if anyone ever uses them?

2. Deprecate --set-upstream as its usage is confusing.

3. Add -u <name> to both checkout and branch to specify the upstream
branch. It is used with checkout -b in cases where an upstream would
not normally be configured, either because it's not the default
according to branch.autosetupmerge or because the start-point is not a
branch. It is used with branch when creating a branch in a similar
manner to how it's used with checkout when creating a branch, but may
also be used to reset the upstream after the fact like so:

   $  git branch -u <upstream> [<branch>]

4. Add --pull-default={rebase,merge} to both checkout and branch used
for setting/unsetting branch.<name>.rebase during initial branch
creation, or after the fact in the case of git-branch. It is an error
to try to set --pull-default if the upstream is not configured, either
automatically or via -u.

Sorry. What I meant was that you'd need the ability to differentiate between "--set-upstream=foo" and "--set-upstream foo" due to git-branch's existing semantics. Right now:

$ git branch --set-upstream topic origin/master

Creates topic from origin/master and sets topic's upstream to origin/master. If --set-upstream suddenly starts taking an argument, that means something completely different: create a new branch named origin/master starting at HEAD and set its upstream to "topic".

I think we're better off just deprecating --set-upstream and introducing the more convenient -u.

j.

Jay Soffian <jaysoffian@gmail.com> wrote:

I use --no-track quite frequently, and I always find it unfortunate that I have to (sometimes I forget). I need it when I want to create a new local branch off of master, and my local master is not up to date, but I'm too lazy to bring it up to date because I have some other branch checked out currently; so I do

  $ git fetch
  $ git checkout -b new_branch origin/master

This will by default make origin/master the upstream branch of new_branch, which is never what I want.

To avoid the problem, I would have to

  $ git checkout master
  $ git pull
  $ git checkout -b new_branch

I guess I would like a config setting of branch.autosetupmerge=onlyifnamematches or some such.

I realize this is probably not related to the discussion of whether or how --set-upstream should be fixed; I just wanted to comment on your question.

Jay Soffian <jaysoffian@gmail.com> writes:

With "git branch <name>" (or for that matter "git branch -d <name>"), we are manipulating some attribute of the branch <name> (namely, "what does it point at", "does it exist?") not of the current branch. So it is natural to expect that some attribute of the named branch origin/master is being changed.

Even though I think I understand the issue you are trying to tackle, I think your proposal seems to make things worse. In either "--set-upstream A" or "--set-upstream=A", it is unclear if you are manipulating "what other branch does this follow" attribute of A or the current branch.

I think it was a misdesign to allow --set-upstream without argument to default to the current branch. Wouldn't it be simpler to just fix the parser so that "--set-upstream A" and "--set-upstream=A" both mean the same thing? The branch whose attribute is manipulated defaults to the current one in either case.

IOW, I don't think

is a sane behaviour from day one, and is simply a bug. Changing this behaviour would merely be a bugfix, not a flag-day event that changes an established behaviour.

But that may be just me. I don't use --set-upstream myself, and people may have learned to be comfortable with the current behaviour.

        If there are people who want to keep the current behaviour, please
        speak up.  Then we can introduce the usual migration procedure to
        first add a configuration to flip the behaviour (default off),
        then warn if you use 0-argument --set-upstream to default to the
        current branch without setting the configuration, and eventually
        flip the default to always require argument to --set-upstream.

If "git branch master --set-upstream origin/master" is accepted, we have another bug in its parser to fix. The canonical command line should always be dashed-options, then refs and then pathspecs.

On Tue, Feb 1, 2011 at 4:15 PM, Junio C Hamano <gitster@pobox.com> wrote:

Okay, our emails criss-crossed. I agree with that, but my other email proposes adding -u <name> with correct behavior and just deprecating --set-upstream. I suppose we could instead (or in addition) just fix --set-upstream.

I guess please reply to the other email so we don't keep criss-crossing. :-)

j.

Jay Soffian <jaysoffian@gmail.com> writes:

BTW, you're just talking about "git branch", right?

['cause the way "--set-upstream" works with "git push" is perfect, and shouldn't be changed...]

-miles

On Tue, Feb 1, 2011 at 11:08 PM, Miles Bader <miles@gnu.org> wrote:

I was talking about git-branch and git-checkout. I didn't realize git-push even had --set-upstream. Interestingly, -u is an alias for --set-upstream with git-push, but not with git-branch.

j.