When pushing a new branch, if you don't specify -u, your local branch is not automatically set up to track the remote branch. So, a contributor does git push, and then wonders why git pull throws such confusing messages. It would be great if the instructions for project maintainers could be updated, such as:

git checkout -b 7.x-1.x
git push -u origin 7.x-1.x


dww’s picture

Project: Drupal.org infrastructure » Project Git instructions
Version: » 6.x-1.x-dev
Component: Git » Documentation

Based on another read of the git push man page, sounds like a good change to me. Moving to the queue for the code that generates the "Git instructions" tab on project nodes.


helmo’s picture

Assigned: Unassigned » eliza411

Seems like a good good idea.

As this part has not landed in code I leave it to eliza411 to fix it in the database.

eliza411’s picture

See also: #1092576: Setup commands should set upstream tracking

Specifically note: #1092576-1: Setup commands should set upstream tracking:
--set-upstream appeared only in Git

I'm not sure if there is an alternative other then editing the .git file manually in previous Git versions.

helmo’s picture

What is the minimal git version we support? As older versions also lack some options for cloning it might be nice to have some faq item for the minimal recommended version.

eliza411’s picture

Status: Active » Closed (won't fix)

@helmo, I asked sdboyer for an official minimum version number, but we don't have one yet. It's dependent on what's included in major distros, etc.

The Git team chose to include directions that were first included in Git 1.6.5 (git clone --branch), so I'd say until we get something more official, instructions we include should work in 1.6.5 and need not work in earlier versions. just came out in December 2010, and sdboyer says it means you won't have it unless you downloaded and installed Git yourself (that is, without using a package manager), so this is getting marked as Closed (won't fix).

Crell’s picture

Status: Closed (won't fix) » Postponed

I hope you don't mind, but I'm going to refile this to postponed. At some point we can reliably expect Git 1.7 (which in my experience is the "good version" from a UX perspective), and at that point we'll want to update the documentation to leverage that version's hotness.

(And really, December 2010? I could have sworn I was using 1.7 long before that.)

dww’s picture

In fact, I daresay we could consider adding sections at the bottoms of certain doc pages with "Already using Git 1.7? You can also..." wisdom.

Crell’s picture

+1 to #7. That would also act as an incentive for people to upgrade when they can. :-)

Even if we don't add -u, isn't there some ugly way to make a branch tracking? That should be included in the instructions as well, otherwise our instructions are telling people to setup an environment that is twice as difficult to use as it needs to be.

eliza411’s picture

Assigned: eliza411 » Unassigned

I've opened a documentation issue for this since the immediate work has nothing to do with Git instructions. I'm +1 to dww's suggestion as well.

When there's consensus on the best practice for making a tracking branch, I'll include it in Git instructions.

Note, the -u option is not about using 1.7, which indeed came out some time ago. sdboyer can explain why the interim Git releases are confusing, but this specifically requires or newer, as I understand it.

The docs issue is available at #1105532: Create a pattern for newer Git commands in the Git docs

sdboyer’s picture

I like the general idea in #7, with the exception of explicitly saying "1.7." As eliza411 points out, it's not about using 1.7. Git's releases are only sequential within patch versions; minor versions see simultaneous releases over a long period of time. Moreover, what about when Git 1.8 comes out? Do we want to go update all our docs? Clearly not. So if we amend it to, "Using a [very] recent version of Git" or somesuch, I'm +1.


As for the actual version that's required, I did a bit of pokin about in git.git:

$ git log --oneline --all --grep='set-upstream'
 ec8460b push: better error messages when push.default = tracking
 786f174 Merge branch 'mm/phrase-remote-tracking'
 4eec6f9 git-branch.txt: mention --set-upstream as a way to change upstream configuration
 81fa024 Merge branch 'maint'
 ff9c082 completion: --set-upstream option for git-branch
 75df714 Makefile: transport.o depends on branch.h now
 0ed3a11 Documentation: move away misplaced 'push --upstream' description
 1a545d0 Merge branch 'il/branch-set-upstream'
 533e8af Merge branch 'il/push-set-upstream'
 85e2233 branch: warn and refuse to set a branch as a tracking branch of itself.
 4fc5006 Add branch --set-upstream
 e9fcd1e Add push --set-upstream

$ git name-rev e9fcd1e
e9fcd1e tags/v1.7.0-rc0~71^2

$ git show v1.7.0-rc0~71^2
 commit e9fcd1e2121100d43d2d212eb6c6f1fc82aade1d
 Author: Ilari Liusvaara <ilari.liusvaara@elisanet.fi>
 Date:   Sat Jan 16 23:45:31 2010 +0200
     Add push --set-upstream
     Frequent complaint is lack of easy way to set up upstream (tracking)
     references for git pull to work as part of push command. So add switch
     --set-upstream (-u) to do just that.
     Signed-off-by: Jeff King <peff@peff.net>
     Signed-off-by: Ilari Liusvaara <ilari.liusvaara@elisanet.fi>
     Signed-off-by: Junio C Hamano <gitster@pobox.com>

$ git show 533e8af
 commit 533e8af50ed6e89eabc421478c9021c4da5f404d
 Merge: 0877510 e9fcd1e
 Author: Junio C Hamano <gitster@pobox.com>
 Date:   Wed Jan 20 14:40:48 2010 -0800
     Merge branch 'il/push-set-upstream'
     * il/push-set-upstream:
       Add push --set-upstream

$ git name-rev 533e8af
533e8af tags/v1.7.0-rc0~71

$ git tag --contains 533e8af

So yeah, the -u option actually WAS available back as of 1.7.0, and ought to be available in all the releases in that list.

sdboyer’s picture

Even if we don't add -u, isn't there some ugly way to make a branch tracking?

$ git config branch.6.x-2.x.remote origin
$ git config branch.6.x-2.x.merge 6.x-2.x

That would set your local 6.x-2.x branch to track origin/6.x-2.x in the exact way git push -u origin 6.x-2.x does.


EDIT: no it won't. git config is dumb, and even if you quote the branch name, it still chokes on dots. Ugh. Basically, you have to copy/paste a config section in .git/config for it to work. :( :( :(

andyceo’s picture

Subscribe! I even did a duplicate issue #1127800: Use option -u for git push in git instruction settings

Using -u option is very usefull.

eliza411’s picture

I did include it on the branching page for now: http://drupal.org/node/1066342. We'll update as soon as is part of common distros.

Crell’s picture

As a random extra data point, it looks like GitHub is now including -u in their "copy these instructions" page on which ours is based. They didn't used to. I guess they consider 1.7 widely deployed enough.

eliza411’s picture

An update: the newer version of Git will be included with the Ubuntu release in a few days. I'll be looking at the major distros again during the first part of May and we should be able to put this out soon.

TR’s picture

Posting this so others can find this issue when they search for the cause of the "confusing message" that git pull throws if you don't use -u when you push out your new branch. The message you will see looks something like this:

You asked me to pull without telling me which branch you
want to merge with, and 'branch.7.x-1.x.merge' in
your configuration file does not tell me, either. Please
specify which branch you want to use on the command line and
try again (e.g. 'git pull <repository> <refspec>').
See git-pull(1) for details.
eliza411’s picture

Assigned: Unassigned » sdboyer

@sdboyer: I'm planning to update the instructions tomorrow unless you have objections. If it causes problems we can always revert and it looks to me like macports and Windows (msysgit) are plenty current.

eliza411’s picture

Status: Postponed » Fixed

I've made this update, without any sort of "Didn't work for you." I'll plan to add that if support requests come in.

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.