Re: [PATCH] Documentation: update git-pull.txt for clone's new default behavior

bfields@fieldses.org writes:

 git pull, git pull origin::
-	Fetch the default head from the repository you cloned
-	from and merge it into your current branch.
+	Update the remote tracking brances for the repository
+	you cloned from, then merge one of them into your
+	current branch.  Normally the branch merged in is
+	the HEAD of the remote repository, when your master
+	branch is checked out.  When on another branch,
+	the (alphabetically) first branch from the remote
+	repository is merged in.  These defaults can be modified
+	using the branch and remote sections of the repository
+	configuration; see gitlink:git-repo-config[1] for details.

I think documenting this is wrong.  At least we should say "do
not be lazy and say 'git pull' or 'git pull origin' without
configuring what branch you are interested in when on a branch
you created yourself".  Later, people can supply patches to make
that configuration easier.

When the user says "pull origin" while on another branch that
does not have branch.$that_branch.merge properly configured, it
happens to find the first remote branch -- which unfortunately
comes from the wildcard remote.origin.fetch created by clone to
say "track all remote branches".

What we wanted to do ideally was to forbid "git pull" that does
not have explicit refspec from the command line, without
configuring branch.*.merge.  However this broke established
workflow of people who has remote.$origin.fetch configured to
list the remote branch to fetch explicitly; the merged branch
selection has always been "the first set of branches listed in
the configuration" and these peoples had their configuration
right without needing to have branch.*.merge at all.

Unfortunately git is too flexible around this area.  

We probably could somehow arrante the remote branches that came
from wildcarding not subject to the merge branch selection
logic, but honestly I am tired of looking at that code for now.

An acceptable short-term workaround might be to revert the
effect of commit 3dd3d5b0.

On Sun, Dec 31, 2006 at 04:35:41PM -0800, Junio C Hamano wrote:

bfields@fieldses.org writes:

quoted

 git pull, git pull origin::
-	Fetch the default head from the repository you cloned
-	from and merge it into your current branch.
+	Update the remote tracking brances for the repository
+	you cloned from, then merge one of them into your
+	current branch.  Normally the branch merged in is
+	the HEAD of the remote repository, when your master
+	branch is checked out.  When on another branch,
+	the (alphabetically) first branch from the remote
+	repository is merged in.  These defaults can be modified
+	using the branch and remote sections of the repository
+	configuration; see gitlink:git-repo-config[1] for details.

I think documenting this is wrong.  At least we should say "do
not be lazy and say 'git pull' or 'git pull origin' without
configuring what branch you are interested in when on a branch
you created yourself".  Later, people can supply patches to make
that configuration easier.

Yeah, OK, I'll admit I felt silly writing that; so for now, how about
just omitting mention of the current behavior and saying instead
something like this?:

	"....  Normally the branch merged in is
	the HEAD of the remote repository, when your master
	branch is checked out.  For branches other than master,
	you can choose the default remote branch to merge using the
	branch.<name>.remote and branch.<name>.merge options; see
	gitlink:git-repo-config[1] for details."

--b.