[PATCH] Docs: update cvs-migration.txt to reflect clone's new default behavior

[PATCH] Docs: update cvs-migration.txt to reflect clone's new default behavior

[bfields]

From: J. Bruce Fields <bfields@citi.umich.edu>

I couldn't think of a really quick way to give all the details, so just refer
readers to the git-repo-config man page instead.

I haven't tested recent cvs import behavior--some time presumably it should be
updated to do something more similar to clone.

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
---
 Documentation/cvs-migration.txt |   11 ++++-------
 1 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/Documentation/cvs-migration.txt b/Documentation/cvs-migration.txt
index b657f45..8e09bea 100644
--- a/Documentation/cvs-migration.txt
+++ b/Documentation/cvs-migration.txt
@@ -34,13 +34,10 @@ them first before running git pull.
 
 [NOTE]
 ================================
-The first `git clone` places the following in the
-`my-project/.git/remotes/origin` file, and that's why the previous step
-and the next step both work.
-------------
-URL: foo.com:/pub/project.git/
-Pull: refs/heads/master:refs/remotes/origin/master
-------------
+The `pull` command knows where to get updates from because of certain
+configuration variables that were set by the first `git clone`
+command; see `git repo-config -l` and the gitlink:git-repo-config[1] man
+page for details.
 ================================
 
 You can update the shared repository with your changes by first committing
-- 
1.5.0.rc0.gac28

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

[bfields]

From: J. Bruce Fields <bfields@citi.umich.edu>

Fix a couple remaining references to the origin branch.

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
---
 Documentation/git-clone.txt |   11 ++++-------
 1 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 874934a..9652320 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -75,16 +75,13 @@ OPTIONS
 	Also the branch heads at the remote are copied directly
 	to corresponding local branch heads, without mapping
 	them to `refs/remotes/origin/`.  When this option is
-	used, neither the `origin` branch nor the default
-	`remotes/origin` file is created.
+	used, neither remote-tracking branches nor the related
+	configuration variables are created.
 
 --origin <name>::
 -o <name>::
-	Instead of using the branch name 'origin' to keep track
-	of the upstream repository, use <name> instead.  Note
-	that the shorthand name stored in `remotes/origin` is
-	not affected, but the local branch name to pull the
-	remote `master` branch into is.
+	Instead of using the remote name 'origin' to keep track
+	of the upstream repository, use <name> instead.
 
 --upload-pack <upload-pack>::
 -u <upload-pack>::
-- 
1.5.0.rc0.gac28

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

[bfields]

From: J. Bruce Fields <bfields@citi.umich.edu>

Update examples.  I'm not sure if the last two examples are really useful
any more.

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
---
 Documentation/git-pull.txt |   75 +++++++++++++++++++++++++------------------
 1 files changed, 44 insertions(+), 31 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 2a5aea7..5b9ff96 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -37,8 +37,15 @@ EXAMPLES
 --------
 
 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.
 
 git pull -s ours . obsolete::
 	Merge local branch `obsolete` into the current branch,
@@ -58,51 +65,57 @@ You should refrain from abusing this option to sneak substantial
 changes into a merge commit.  Small fixups like bumping
 release/version name would be acceptable.
 
-Command line pull of multiple branches from one repository::
+Pull of multiple branches from one repository using default configuration::
 +
 ------------------------------------------------
-$ cat .git/remotes/origin
-URL: git://git.kernel.org/pub/scm/git/git.git
-Pull: master:origin
-
+$ git repo-config -l
+...
+remote.origin.url=git://git.kernel.org/pub/scm/git/git.git
+remote.origin.fetch=+refs/heads/*:refs/remotes/foo/*
+branch.master.remote=origin
+branch.master.merge=refs/heads/master
 $ git checkout master
-$ git fetch origin master:origin +pu:pu maint:maint
-$ git pull . origin
+$ git fetch origin
+$ git pull . origin/master
 ------------------------------------------------
 +
-Here, a typical `.git/remotes/origin` file from a
+Here, a typical configuration created by the
 `git-clone` operation is used in combination with
-command line options to `git-fetch` to first update
-multiple branches of the local repository and then
-to merge the remote `origin` branch into the local
-`master` branch.  The local `pu` branch is updated
-even if it does not result in a fast forward update.
+`git-fetch` to update all of the remote tracking
+branches for `origin` (the remote repository which
+you originally cloned from).  Thanks to the "+" on
+the `remote.origin.fetch` line, the tracking branches
+will all be updated even if they do not result in a
+fast forward update.
++
+The `git pull` command then merges the newly
+fetched origin/master into the local `master` branch.
 Here, the pull can obtain its objects from the local
 repository using `.`, as the previous `git-fetch` is
 known to have already obtained and made available
 all the necessary objects.
++
+Note that given the configuration above, a simple
+`git pull` would have the same result as the above
+sequence of fetch and pull.
 
 
-Pull of multiple branches from one repository using `.git/remotes` file::
+Commandline pull of multiple branches from one repository::
 +
 ------------------------------------------------
-$ cat .git/remotes/origin
-URL: git://git.kernel.org/pub/scm/git/git.git
-Pull: master:origin
-Pull: +pu:pu
-Pull: maint:maint
-
 $ git checkout master
-$ git pull origin
+$ git fetch origin master:origin +pu:pu maint:maint
+$ git pull . origin
 ------------------------------------------------
 +
-Here, a typical `.git/remotes/origin` file from a
-`git-clone` operation has been hand-modified to include
-the branch-mapping of additional remote and local
-heads directly.  A single `git-pull` operation while
-in the `master` branch will fetch multiple heads and
-merge the remote `origin` head into the current,
-local `master` branch.
+Assuming the same configuration as above, this overrides
+the default fetch behavior, updating (or creating, as
+necessary) branches "origin", "pu", and "maint" in the
+local repository by fetching from the branches (respectively)
+"master", "pu", and "maint" from the remote repository.
++
+The "pu" branch will be updated even if it is does not
+fast-foward; the others will not be.
 
 
 If you tried a pull which resulted in a complex conflicts and
@@ -112,7 +125,7 @@ gitlink:git-reset[1].
 
 SEE ALSO
 --------
-gitlink:git-fetch[1], gitlink:git-merge[1]
+gitlink:git-fetch[1], gitlink:git-merge[1], gitlink:git-repo-config[1]
 
 
 Author
-- 
1.5.0.rc0.gac28

[PATCH] Documentation: update glossary entry for "origin"

[bfields]

From: J. Bruce Fields <bfields@citi.umich.edu>

Update glossary entry for "origin" to reflect fact that it normally now refers
to a remote repository, not a branch.

Also, warning not to work on remote-tracking branches is no longer necessary
since git doesn't allow that.

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
---
 Documentation/glossary.txt |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/Documentation/glossary.txt b/Documentation/glossary.txt
index 894883d..7c1a659 100644
--- a/Documentation/glossary.txt
+++ b/Documentation/glossary.txt
@@ -188,11 +188,12 @@ octopus::
 	predator.
 
 origin::
-	The default upstream tracking branch. Most projects have at
+	The default upstream repository. Most projects have at
 	least one upstream project which they track. By default
 	'origin' is used for that purpose.  New upstream updates
-	will be fetched into this branch; you should never commit
-	to it yourself.
+	will be fetched into remote tracking branches named
+	origin/name-of-upstream-branch, which you can see using
+	"git branch -r".
 
 pack::
 	A set of objects which have been compressed into one file (to save
-- 
1.5.0.rc0.gac28

[PATCH] Documentation: remove master:origin example from pull-fetch-param.txt

[bfields]

From: J. Bruce Fields <bfields@citi.umich.edu>

This is no longer a useful example.

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
---
 Documentation/pull-fetch-param.txt |    4 ----
 1 files changed, 0 insertions(+), 4 deletions(-)

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index e852f41..8d4e950 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -39,10 +39,6 @@ checkout -b my-B remote-B`).  Run `git fetch` to keep track of
 the progress of the remote side, and when you see something new
 on the remote branch, merge it into your development branch with
 `git pull . remote-B`, while you are on `my-B` branch.
-The common `Pull: master:origin` mapping of a remote `master`
-branch to a local `origin` branch, which is then merged to a
-local development branch, again typically named `master`, is made
-when you run `git clone` for you to follow this pattern.
 +
 [NOTE]
 There is a difference between listing multiple <refspec>
-- 
1.5.0.rc0.gac28

[PATCH] Documentation: update tutorial's discussion of origin

[bfields]

From: J. Bruce Fields <bfields@citi.umich.edu>

Update tutorial's discussion of origin branch to reflect new defaults,
and include a brief mention of git-repo-config.

Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
---
 Documentation/tutorial.txt |   25 +++++++++++++++----------
 1 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index cb808d9..d043e84 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -323,20 +323,25 @@ $ git pull
 
 Note that he doesn't need to give the path to Alice's repository;
 when Bob cloned Alice's repository, git stored the location of her
-repository in the file .git/remotes/origin, and that location is used
-as the default for pulls.
-
-Bob may also notice a branch in his repository that he didn't create:
+repository in the repository configuration, and that location is
+used for pulls:
 
 -------------------------------------
-$ git branch
-* master
-  origin
+$ git repo-config --get remote.origin.url
+/home/bob/myrepo
 -------------------------------------
 
-The "origin" branch, which was created automatically by "git clone",
-is a pristine copy of Alice's master branch; Bob should never commit
-to it.
+(The complete configuration created by git-clone is visible using
+"git repo-config -l", and the gitlink:git-repo-config[1] man page
+explains the meaning of each option.)
+
+Git also keeps a pristine copy of Alice's master branch under the
+name "origin/master":
+
+-------------------------------------
+$ git branch -r
+  origin/master
+-------------------------------------
 
 If Bob later decides to work from a different host, he can still
 perform clones and pulls using the ssh protocol:
-- 
1.5.0.rc0.gac28

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

[Junio C Hamano]

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.

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

[J. Bruce Fields]

On Sun, Dec 31, 2006 at 04:35:41PM -0800, Junio C Hamano wrote:
> 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.

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.

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

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> 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.

I am still tired of looking at the code, but I would rather 
look at it now than having to still look at it next year.

How about doing this?  The difference this time around is that
if you have non-wildcard refspec listed first, which usually
is the case for people with established git workflow with
existing repositories, we use the old-and-proven rule to
merge the first set of refs.  An earlier round botched this
completely by basing the logic on lack of branch.*.merge,
which broke for many people.

-- >8 --
[PATCH] Do not merge random set of refs out of wildcarded refs

When your fetch configuration has only the wildcards, we would
pick the lexicographically first ref from the remote side for
merging, which was complete nonsense.  Make sure nothing except
the one that is specified with branch.*.merge is merged in this
case.

Signed-off-by: Junio C Hamano <junkio@cox.net>

---

diff --git a/git-parse-remote.sh b/git-parse-remote.sh
index 144f170..d2e4c2b 100755
--- a/git-parse-remote.sh
+++ b/git-parse-remote.sh
@@ -76,16 +76,32 @@ get_remote_default_refs_for_push () {
 # from get_remote_refs_for_fetch when it deals with refspecs
 # supplied on the command line.  $ls_remote_result has the list
 # of refs available at remote.
+#
+# The first token returned is either "explicit" or "glob"; this
+# is to help prevent randomly "globbed" ref from being chosen as
+# a merge candidate
 expand_refs_wildcard () {
+	first_one=yes
 	for ref
 	do
 		lref=${ref#'+'}
 		# a non glob pattern is given back as-is.
 		expr "z$lref" : 'zrefs/.*/\*:refs/.*/\*$' >/dev/null || {
+			if test -n "$first_one"
+			then
+				echo "explicit"
+				first_one=
+			fi
 			echo "$ref"
 			continue
 		}
 
+		# glob
+		if test -n "$first_one"
+		then
+			echo "glob"
+			first_one=
+		fi
 		from=`expr "z$lref" : 'z\(refs/.*/\)\*:refs/.*/\*$'`
 		to=`expr "z$lref" : 'zrefs/.*/\*:\(refs/.*/\)\*$'`
 		local_force=
@@ -116,7 +132,8 @@ canon_refs_list_for_fetch () {
 	if test "$1" = "-d"
 	then
 		shift ; remote="$1" ; shift
-		set x $(expand_refs_wildcard "$@")
+		set $(expand_refs_wildcard "$@")
+		is_explicit="$1"
 		shift
 		if test "$remote" = "$(get_default_remote)"
 		then
@@ -125,6 +142,10 @@ canon_refs_list_for_fetch () {
 			merge_branches=$(git-repo-config \
 			    --get-all "branch.${curr_branch}.merge")
 		fi
+		if test -z "$merge_branches" && test $is_explicit != explicit
+		then
+			merge_branches=..this.will.never.match.any.ref..
+		fi
 	fi
 	for ref
 	do

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

[Luben Tuikov]

--- Junio C Hamano <junkio@cox.net> wrote:
> Junio C Hamano <junkio@cox.net> writes:
> 
> > 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.
> 
> I am still tired of looking at the code, but I would rather 
> look at it now than having to still look at it next year.
> 
> How about doing this?  The difference this time around is that
> if you have non-wildcard refspec listed first, which usually
> is the case for people with established git workflow with
> existing repositories, we use the old-and-proven rule to
> merge the first set of refs.  An earlier round botched this
> completely by basing the logic on lack of branch.*.merge,
> which broke for many people.

Can we please instead revisit the "branch.<name>.remote"
and "branch.<name>.merge" options?

What I'd really like to see and what really would be useful
to me every day is if I could individually _address_ a
"branch.<name>.remote" and "branch.<name>.merge" pair of
options.

I.e. I'd like to say "git-pull parent" or "git-pull parents"
in such and such branch, and this would pull the designated
parent(s) for the current branch.  But if I'm in a different
branch (of the same repo) then the meaning of "parent" changes
accordingly.

Currently, the parent<-->child branch relationship only
exists in paper: for example: git master is the parent for
all my (local) branches, "git-upstream" is child of "next",
"git-lt-work" is child of "git-upstream" and "git-home" is
child of "git-lt-work", each one introducing its own
customizations and changes.  I currently do the pull/merge
by hand, remembering the child/parent relationship and enforcing
it manually by the strict pull/merge sequence I do.

Of course we shouldn't break existing usages like
for example "git-pull . tag ...".

I can achieve the same thing using the "branch.*" options
today, but I do "git-pull" and I'm not entrirely satisfied
with that since in my head I know I'm doing a "parent->child"
merge and would like to express that on the command line.

So this is something of a cross between the remotes/ and
"branch.*" option.

For example "branch.<name>.<symbolic_ref>.fetch" and
"branch.<name>.<symbolic_ref>.merge" would do the trick.

Then at prompt, I say "git-pull <symbolic_ref>" which will
match local branch and symbolic name to whatever matches.

Of course, "branch..<symbolic_name>.*" would seem to be
identical to remotes.  We should disallow that by stipulating
that a non-empty symbolic name imples non-empty branch name.
"branch.<name>..*" would be identical to its current usage.

The point is that the symbolic name changes its designation depending
on which is the current branch, and with a name like "parent" that
makes sense.

    Luben

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

[J. Bruce Fields]

On Sun, Dec 31, 2006 at 07:29:22PM -0800, Luben Tuikov wrote:
> I.e. I'd like to say "git-pull parent" or "git-pull parents"
> in such and such branch, and this would pull the designated
> parent(s) for the current branch.  But if I'm in a different
> branch (of the same repo) then the meaning of "parent" changes
> accordingly.

Could you explain a situation where this would be useful?  A
"parent<-->child" relationship, where there's one upstream branch that
is always merged in, is easily handled; just replace your "git pull
parent" by a "git pull", right?  Am I misunderstanding the proposal?

And is there any reason why your proposal conflicts with Junio's?

--b.

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

[Luben Tuikov]

--- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> On Sun, Dec 31, 2006 at 07:29:22PM -0800, Luben Tuikov wrote:
> > I.e. I'd like to say "git-pull parent" or "git-pull parents"
> > in such and such branch, and this would pull the designated
> > parent(s) for the current branch.  But if I'm in a different
> > branch (of the same repo) then the meaning of "parent" changes
> > accordingly.
> 
> Could you explain a situation where this would be useful?

I don't know how to respond to this question.

>  A
> "parent<-->child" relationship, where there's one upstream branch that
> is always merged in, is easily handled;

e is the base of natural logarithms.

> just replace your "git pull parent" by a "git pull", right?

Yes, but I don't want to just type "git-pull", I want to explicitly
type "git-pull parent" and depending in which branch I'm at, "parent"
would have identical meaning but would merge a different branch... because
I'm in a different branch...

(Since this is what is actually ment by the "branch.*" options.)

> Am I misunderstanding the proposal?

I did give an example of usage in my email to which you replied.

Basically I'd like to extend the concept of "branch spec" locally.

> And is there any reason why your proposal conflicts with Junio's?

Yes.  Beating on a dead horse.  "branch.*" options simply do not cut it.
We can either get rid of them completely or extend them to where they
are actually useful.  Globbing resolution is secondary to resolving
the methodology.

HTH,
    Luben

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

[J. Bruce Fields]

On Sun, Dec 31, 2006 at 09:13:49PM -0800, Luben Tuikov wrote:
> Yes, but I don't want to just type "git-pull", I want to explicitly
> type "git-pull parent" and depending in which branch I'm at, "parent"
> would have identical meaning but would merge a different branch... because
> I'm in a different branch...

Wouldn't it do what you want if by default "git branch new" and "git
checkout -b new" set branch.* options that pointed at the "parent"
branch?

The only reason I can see to require the extra bit of syntax ("git-pull
parent" instead of "git-pull") is if for the same branch you expect to
sometimes pull from one source and sometimes from another, and the pulls
from those various sources are common enough that it's worth defining
some shortcuts for more than one of them.

I can imagine sometimes doing that.  (E.g. if you pull into your master
branch from upstream and from local topic branches.)  But in that case
having to give the remote and branch name explicitly doesn't seem so
bad.

I dunno....

--b.

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

[Luben Tuikov]

--- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> On Sun, Dec 31, 2006 at 09:13:49PM -0800, Luben Tuikov wrote:
> > Yes, but I don't want to just type "git-pull", I want to explicitly
> > type "git-pull parent" and depending in which branch I'm at, "parent"
> > would have identical meaning but would merge a different branch... because
> > I'm in a different branch...
> 
> Wouldn't it do what you want if by default "git branch new" and "git
> checkout -b new" set branch.* options that pointed at the "parent"
> branch?

Technically yes.  Presentationally no.

> The only reason I can see to require the extra bit of syntax ("git-pull
> parent" instead of "git-pull") is if for the same branch you expect to
> sometimes pull from one source and sometimes from another, and the pulls
> from those various sources are common enough that it's worth defining
> some shortcuts for more than one of them.

Exactly.

> I can imagine sometimes doing that.  (E.g. if you pull into your master
> branch from upstream and from local topic branches.)  But in that case
> having to give the remote and branch name explicitly doesn't seem so
> bad.

Basically I want to _name_ the dependency, instead of having it be
implicit.  One can extend that dependency, in more complicated
topic branch relationship, where for example, C extends B, B extends
A, A extends master, but B' also extends A, consider B' a "version"
of the extension which B implements.  This is of course a trivial
example and more complicated ones exist.

Naming the dependency would give git greater coverage when it needs
to implement complicated source development environments and code
relationship. IOW, it is the way to go.  Having a single implicit
dependency is just a crutch, half-way there.

Or, one can look at it in a different way, extending the
remote/ functionality as is, but instead of being remote-pulls-
into-local, extending for local pulls into local.

I.e. the remote relationship is named,  I'd like to extend
this locally as well.

Consider the examples of "branch.<name>.<symbolic_ref>.{fetch, merge}"
I gave in a previous email in this thread.

     Luben

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

[Junio C Hamano]

Luben Tuikov <ltuikov@yahoo.com> writes:

> --- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> ...
>> Could you explain a situation where this would be useful?
>
> I don't know how to respond to this question.
>
>>  A
>> "parent<-->child" relationship, where there's one upstream branch that
>> is always merged in, is easily handled;
>
> e is the base of natural logarithms.

You lost me here; I am guessing this is some sarcasm not worth
paying attention to, so I'd ignore this part for now.

>> just replace your "git pull parent" by a "git pull", right?
>
> Yes, but I don't want to just type "git-pull", I want to explicitly
> type "git-pull parent" and depending in which branch I'm at, "parent"
> would have identical meaning but would merge a different branch... because
> I'm in a different branch...
>
>> Am I misunderstanding the proposal?
>
> I did give an example of usage in my email to which you replied.

But what confuses me (and I think JBF shares the same confusion
with me) is that you had only one example "parent".

While I understand that it would make sense to define "parent"
for each branch in a downstream developer's workflow, (1) I do
not see the difference between your wording, "parent", and what
we traditionally have called "origin", and (2) I do not think of
relationship other than "parent" ("origin") that is applicable
commonly (in other words, "worth having your 'symbolic'
mechanism for, because it is so commonly applicable") to
branches offhand.  Hence, JBF's suggestion to use "git pull"
without using noiseword "parent" or "origin" feels very natural
to me --- if there can be only one valid thing to say, why do
you even have to say it?

Because I do not understand what you would want "parent" for and
why "git pull" is not sufficient, I cannot tell if this would
help solving what you are trying to solve in a different way,
but I suspect a useful thing to have might be a per-branch
alias.  For example, we could allow "git merge" without
parameters to alias to "git merge origin/next" when you are on
your 'next' and the same "git merge" could be aliased to "git
merge origin/master" when you are on your 'master'.

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

[Luben Tuikov]

--- Junio C Hamano <junkio@cox.net> wrote:
> Luben Tuikov <ltuikov@yahoo.com> writes:
> 
> > --- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > ...
> >> Could you explain a situation where this would be useful?
> >
> > I don't know how to respond to this question.
> >
> >>  A
> >> "parent<-->child" relationship, where there's one upstream branch that
> >> is always merged in, is easily handled;
> >
> > e is the base of natural logarithms.
> 
> You lost me here; I am guessing this is some sarcasm not worth
> paying attention to, so I'd ignore this part for now.

Absolutely correct. I just needed to respond to an obvious fact with
another obvious fact.

> >> just replace your "git pull parent" by a "git pull", right?
> >
> > Yes, but I don't want to just type "git-pull", I want to explicitly
> > type "git-pull parent" and depending in which branch I'm at, "parent"
> > would have identical meaning but would merge a different branch... because
> > I'm in a different branch...
> >
> >> Am I misunderstanding the proposal?
> >
> > I did give an example of usage in my email to which you replied.
> 
> But what confuses me (and I think JBF shares the same confusion
> with me) is that you had only one example "parent".

More complicated and exotic examples exist.  See my response
to JBF, which I just posted a moment ago.

> While I understand that it would make sense to define "parent"

No, no, no.  Forget about the semantic attibute of "parent".
I could've called it "xyz" for that matter.

What I'm talking about is the concept of "branch spec".  It
is a well known concept in SCMs.

We currently implement it, in git specific way, for remotes/
only, but not for local ("topic") branches.

Another way to look at it is that a Topic, can have many
other self-contained sub-Topics, each one building on the one
"before" it, extending it, yet introducing new functionality,
and only in the "leaf" branch, do you get a fully capable software.
Each sub-topic branch is also a working software but only implements
part of the functionality of your product and/or toned down version
of it, say if someone doesn't want support for feature ABC, which
uses 100MiB of memory...

> for each branch in a downstream developer's workflow, (1) I do
> not see the difference between your wording, "parent", and what
> we traditionally have called "origin",

I've always contended that it is the same and had mentioned
that it is only implemented for remotes/.

> and (2) I do not think of
> relationship other than "parent" ("origin") that is applicable
> commonly (in other words, "worth having your 'symbolic'
> mechanism for, because it is so commonly applicable") to
> branches offhand.  Hence, JBF's suggestion to use "git pull"
> without using noiseword "parent" or "origin" feels very natural
> to me --- if there can be only one valid thing to say, why do
> you even have to say it?

Well, this is the question...  Can you stipulate that there is
only _one_ valid thing to say?  Wouldn't it be easier to generalize
the concept of "branch spec" to local "topic" branches as we do
now for remotes/.  Wouldn't this allow people to have more freedom
at what and how they'd like to set their software dependencies?

The SCM industry seem to have generalized this with the
concept of a "branch spec".

> Because I do not understand what you would want "parent" for and
> why "git pull" is not sufficient,

Because it _implicitly_ defines the relationship.  Nothing wrong
with that, but also allowing an explicit naming of the relationship,
as is currently done for remotes/, would give git much, much more
power to define even the most complicated software development
setup (locally).

As I pointed out before, "branch.<name>..{fetch,merge}" would
cover the "git-pull" case.  "branch..<symbolic-ref>.{fetch,merge}"
should be illegal since it is the same as remotes/, and
"branch.<name>.<symbolic-ref>.{fetch, merge}" matches
"git-pull <symbolic-ref>".

> I cannot tell if this would
> help solving what you are trying to solve in a different way,

1) It would help solve it the proper way and,
2) it would give git the concept of "branch spec" universally, i.e.
local branches as well as remotes.

> but I suspect a useful thing to have might be a per-branch
> alias.  For example, we could allow "git merge" without
> parameters to alias to "git merge origin/next" when you are on
> your 'next' and the same "git merge" could be aliased to "git
> merge origin/master" when you are on your 'master'.

Any why not solve the absolute general case forever, by
implementing what I have described above, and move on
to more interesting things?

     Luben

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

[Theodore Tso]

Luben,

Let me see if I can understand what you are asking for without using
the term "branch spec", which I don't think has been adequately
defined yet in this thread.  (Where "the SCM industry has adopted"
isn't a definition.  :-)

Currently, today, if you type:

	git fetch <non-URL>

... it will look up "<non-URL>" in a single global namespace, which
(using only the new config scheme) is looked up in remote.<non-URL>
and remote.<non-URL>.{url,fetch} is used to control the operation of
git-fetch.

What you want to do is to change this to where:

	git fetch <non-URL>

...will now lookup "<non-URL>" in a namespace which is qualified by
the branch that you are in.  So you want to look up the information in
branches.<current-branch>.<non-URL>.{url,fetch} instead.

You haven't stated it explicitly, but I assume that if
branches.<current-branch>.<non-URL> doesn't exist, you're proposing
that the code fall back to looking in the old configuration parameter,
remote.<non-URL>, so that certain names that should be global can
continue to be global, and that people who want a single global
namespace can continue to have it?

Is that your proposal, stripped of the arguments of why you want it,
and of the somewhat confusing "parent" example (which is a bad one
given that your "git pull parent" example was the semantic equivalent
of "git pull")?

If it is, I'm a bit nervous since it's making the git-fetch command
modal, and modal UI's are confusing to users.  On the other hand, it's
a fundamental modality we have already (based on the question "which
branch am I"), and there are hacks that will allow you to put the
current branch into your command-line.  And as long as you are
proposing a lookup in branches.current.branch.<non-URL> first before
checking remotes.<non-URL> it seems mostly harmless to me.  I doubt
I'd ever use it, but maybe it would be helpful to some.

						- Ted

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

[Luben Tuikov]

--- Theodore Tso <tytso@mit.edu> wrote:
> Luben,
> 
> Let me see if I can understand what you are asking for without using
> the term "branch spec", which I don't think has been adequately
> defined yet in this thread.  (Where "the SCM industry has adopted"
> isn't a definition.  :-)

You can also think of it as "the merge direction given a symbolic name".

> Currently, today, if you type:
> 
> 	git fetch <non-URL>
> 
> ... it will look up "<non-URL>" in a single global namespace, which
> (using only the new config scheme) is looked up in remote.<non-URL>
> and remote.<non-URL>.{url,fetch} is used to control the operation of
> git-fetch.

I'm talking about more in terms of git-merge, but since git-pull
is a git-fetch and git-merge, I've been using git-pull for completeness.
IOW, I've tried to concentrate on a per-repo operations (merge) as opposed
to on a multi-repo, which is currently handled by git as is expected.

> What you want to do is to change this to where:
> 
> 	git fetch <non-URL>

git-pull, for completeness.  See my paragraph above.

> ...will now lookup "<non-URL>" in a namespace which is qualified by
> the branch that you are in.  So you want to look up the information in
> branches.<current-branch>.<non-URL>.{url,fetch} instead.

More specifically,
branch.<branch-match>.<symbolic-ref match>.{fetch,merge}.

branch.<branch-match>..{fetch,merge} is allowed and defalts
to already implemented "git-pull".

branch..<symbolic-ref match>.{fetch,merge} is forbidden
since it is essentially remotes/ and is handled by the current
"remotes/" infrastructure by git.

branch.<branch-match>.<symbolic-ref match>.{fetch,merge} will
perform the fetch, which would be a no-op, since the branch
we're "fetching" is local, and the merge merges into the
current branch if it matches.

> You haven't stated it explicitly, but I assume that if
> branches.<current-branch>.<non-URL> doesn't exist, you're proposing
> that the code fall back to looking in the old configuration parameter,
> remote.<non-URL>, so that certain names that should be global can
> continue to be global, and that people who want a single global
> namespace can continue to have it?

Yes, I absolutely do not want to break existing behavior.  But
if it is extended, it should be done properly, and a general
case should be solved as to solve this once and forever.

> Is that your proposal, stripped of the arguments of why you want it,
> and of the somewhat confusing "parent" example (which is a bad one
> given that your "git pull parent" example was the semantic equivalent
> of "git pull")?

More or less.  Basically, I want local "git-pull" (fetch[no-op],merge)
to be addressable, i.e. _named_, so that I can establish a more complex
software dependency, which I currently do, my means of the order and
the type of "git-pull . <branch>" I do.

> If it is, I'm a bit nervous since it's making the git-fetch command
> modal, and modal UI's are confusing to users.

Think of "git-pull", not just of "git-fetch".  As well as think
of a setup where there are more than one branch implementing
software dependency, resolving to a software product.

> On the other hand, it's
> a fundamental modality we have already (based on the question "which
> branch am I"), and there are hacks that will allow you to put the
> current branch into your command-line.

Ah, yes.  Well, the many-branches-one-directory is confusing and
is modal.  *But*, it doesn't have to be like that.  Git allows
the freedom to define branch-per-directory-yet-single-repo which I've
absolutely always used with GIT, and other SCMs.  This way it is
absolutely unambiguous "what branch I'm at".

It is in this sense that I do "cd <branch>; git-pull . <branch>"
in a sequence, and I'd rather do "cd <branch>; git-pull <symbolic-ref>"
to define which branch is the merge coming from given the current branch
_and_ the symbolic ref.

> And as long as you are
> proposing a lookup in branches.current.branch.<non-URL> first before
> checking remotes.<non-URL> it seems mostly harmless to me.  I doubt
> I'd ever use it, but maybe it would be helpful to some.

Yes, current behavior should absolutely not be broken.
First (<current-branch>,<symbolic-ref>) is matched against
"branch.<name>.<symbolic-ref>.{fetch,merge}" modulo the 
cases I've outlined before, and then if everything else
fails, we default to remote/.

     Luben

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

[Theodore Tso]

On Mon, Jan 01, 2007 at 03:56:05PM -0800, Luben Tuikov wrote:
> > Currently, today, if you type:
> > 
> > 	git fetch <non-URL>
> > 
> > ... it will look up "<non-URL>" in a single global namespace, which
> > (using only the new config scheme) is looked up in remote.<non-URL>
> > and remote.<non-URL>.{url,fetch} is used to control the operation of
> > git-fetch.
> 
> I'm talking about more in terms of git-merge, but since git-pull
> is a git-fetch and git-merge, I've been using git-pull for completeness.

Well, yes; since git-pull is implemented in terms of git-fetch
followed by a git-merge, that's why I talked about git-fetch.  It is
git-fetch which uses remote.<non-URL>.{url,fetch}, not git-merge or
git-pull (since it just passes those arguments over to git-fetch).

> More specifically,
> branch.<branch-match>.<symbolic-ref match>.{fetch,merge}.

What do you mean by <branch-match> and <symbolic-ref match>?

Are you assuming some kind of glob match?  If so, what are the
specific rules of the match that you are proposing?

> branch.<branch-match>..{fetch,merge} is allowed and defalts
> to already implemented "git-pull".

What do you mean by ".." here?   

> Think of "git-pull", not just of "git-fetch".  As well as think
> of a setup where there are more than one branch implementing
> software dependency, resolving to a software product.

git-pull is implemented in terms of git-fetch.  So if we make the
change to git-fetch, the changes naturally follow to git-pull.  Or are
you proposing to change that?

						- Ted

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

[Luben Tuikov]

--- Theodore Tso <tytso@mit.edu> wrote:
> Well, yes; since git-pull is implemented in terms of git-fetch
> followed by a git-merge, that's why I talked about git-fetch.  It is
> git-fetch which uses remote.<non-URL>.{url,fetch}, not git-merge or
> git-pull (since it just passes those arguments over to git-fetch).
> 
> > More specifically,
> > branch.<branch-match>.<symbolic-ref match>.{fetch,merge}.
> 
> What do you mean by <branch-match> and <symbolic-ref match>?
> 
> Are you assuming some kind of glob match?  If so, what are the
> specific rules of the match that you are proposing?

Yes. I've outlined them at least twice in this thread
already as well as in that same email of mine which you're replying
to, which I'm replying to.

> > branch.<branch-match>..{fetch,merge} is allowed and defalts
> > to already implemented "git-pull".
> 
> What do you mean by ".." here?   

I mean "git-pull", as opposed to "git-pull <symbolic-ref>".

I.e. "branch.<branch-match>..{fetch,merge}" matches no symbolic
ref given, exactly what it defines.

> > Think of "git-pull", not just of "git-fetch".  As well as think
> > of a setup where there are more than one branch implementing
> > software dependency, resolving to a software product.
> 
> git-pull is implemented in terms of git-fetch.  So if we make the
> change to git-fetch, the changes naturally follow to git-pull.  Or are
> you proposing to change that?

No, not at all.

Please see my last email to Junio in this thread.  Depending on
how this new functionlity is implemented for git 1.5, the concept
of "branch spec" can be had by using a "dummy" [remote] spec,
used only as a command line match, and specifying the merge
dependency in the [branch] spec, refering to "remote" and
identifying what to merge.  See that email please.

    Luben

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

[Junio C Hamano]

Luben Tuikov <ltuikov@yahoo.com> writes:

> It is in this sense that I do "cd <branch>; git-pull . <branch>"
> in a sequence, and I'd rather do "cd <branch>; git-pull <symbolic-ref>"
> to define which branch is the merge coming from given the current branch
> _and_ the symbolic ref.

If I am reading you correctly, you have multiple directories,
each with its own .git/ directory but major parts of these .git/
directories are shared (namely, objects/ and refs/).  You would
not be able to have separate checkout in these directories if
you shared .git/HEAD and .git/index, so at least each of these
directories has these two files for its own.

Is that what you are doing?

If that is the case, I think you do not even have to have the
"branch spec" to express the patchflow among them.  Essentially
you are using "one branch, one directory, one repository"
workflow (my understanding is that this is how BK worked but I
haven't seen it) but with your own improvements.  The reason
this is an improvement is because such a shared .git/refs/
allows you to do diff and log across branches this way, so if
you have a separate .git/config just like you already have
separate .git/HEAD and .git/index in these directories, you can
use [remote "xyz"] sections in each of them to achieve what you
called 'symbolic'.

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

[Luben Tuikov]

--- Junio C Hamano <junkio@cox.net> wrote:
> Luben Tuikov <ltuikov@yahoo.com> writes:
> 
> > It is in this sense that I do "cd <branch>; git-pull . <branch>"
> > in a sequence, and I'd rather do "cd <branch>; git-pull <symbolic-ref>"
> > to define which branch is the merge coming from given the current branch
> > _and_ the symbolic ref.
> 
> If I am reading you correctly, you have multiple directories,
> each with its own .git/ directory but major parts of these .git/
> directories are shared (namely, objects/ and refs/).  You would
> not be able to have separate checkout in these directories if
> you shared .git/HEAD and .git/index, so at least each of these
> directories has these two files for its own.
> 
> Is that what you are doing?

Yes, but the _ONLY_ thing which is NOT shared is .git/HEAD and
.git/index.  EVERYTHING else is the _same_ in all branch-per-directory.

> If that is the case, I think you do not even have to have the
> "branch spec" to express the patchflow among them.  Essentially
> you are using "one branch, one directory, one repository"
> workflow (my understanding is that this is how BK worked but I
> haven't seen it) but with your own improvements.  The reason
> this is an improvement is because such a shared .git/refs/
> allows you to do diff and log across branches this way, so if
> you have a separate .git/config just like you already have
> separate .git/HEAD and .git/index in these directories, you can
> use [remote "xyz"] sections in each of them to achieve what you
> called 'symbolic'.

Yeah, but I do not want to introduce yet another non-shared
file -- namely the config.

I want the config to be shared as well, since the repo is
exactly the same.  Firthermore, the branches are branches of
the same repo, not of different one.  config should be one
and the same -- per repo.

   Luben

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

[J. Bruce Fields]

On Sun, Dec 31, 2006 at 05:44:37PM -0800, Junio C Hamano wrote:
> How about doing this?  The difference this time around is that
> if you have non-wildcard refspec listed first, which usually
> is the case for people with established git workflow with
> existing repositories, we use the old-and-proven rule to
> merge the first set of refs.  An earlier round botched this
> completely by basing the logic on lack of branch.*.merge,
> which broke for many people.

Updated man page assuming that change; does this look any better?

--b.

[PATCH] Documentation: update git-pull.txt for new clone behavior

Update examples, stop using branch named "origin" as an example.
Remove large example of use of remotes; that particular case is
nicely automated by default, so it's not so pressing to explain, and
we can refer to git-repo-config for the details.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/git-pull.txt |   69 ++++++++++++++++----------------------------
 1 files changed, 25 insertions(+), 44 deletions(-)

diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
index 2a5aea7..13be992 100644
--- a/Documentation/git-pull.txt
+++ b/Documentation/git-pull.txt
@@ -37,17 +37,27 @@ EXAMPLES
 --------
 
 git pull, git pull origin::
-	Fetch the default head from the repository you cloned
-	from and merge it into your current branch.
-
-git pull -s ours . obsolete::
-	Merge local branch `obsolete` into the current branch,
-	using `ours` merge strategy.
+	Update the remote-tracking branches 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, but the choice is
+	determined by the branch.<name>.remote and
+	branch.<name>.merge options; see gitlink:git-repo-config[1]
+	for details.
+
+git pull origin next::
+	Merge into the current branch the remote branch `next`;
+	leaves a copy of `next` temporarily in FETCH_HEAD, but
+	does not update any remote-tracking branches.
 
 git pull . fixes enhancements::
 	Bundle local branch `fixes` and `enhancements` on top of
 	the current branch, making an Octopus merge.
 
+git pull -s ours . obsolete::
+	Merge local branch `obsolete` into the current branch,
+	using `ours` merge strategy.
+
 git pull --no-commit . maint::
 	Merge local branch `maint` into the current branch, but
 	do not make a commit automatically.  This can be used
@@ -61,48 +71,19 @@ release/version name would be acceptable.
 Command line pull of multiple branches from one repository::
 +
 ------------------------------------------------
-$ cat .git/remotes/origin
-URL: git://git.kernel.org/pub/scm/git/git.git
-Pull: master:origin
-
 $ git checkout master
-$ git fetch origin master:origin +pu:pu maint:maint
-$ git pull . origin
+$ git fetch origin +pu:pu maint:tmp
+$ git pull . tmp
 ------------------------------------------------
 +
-Here, a typical `.git/remotes/origin` file from a
-`git-clone` operation is used in combination with
-command line options to `git-fetch` to first update
-multiple branches of the local repository and then
-to merge the remote `origin` branch into the local
-`master` branch.  The local `pu` branch is updated
-even if it does not result in a fast forward update.
-Here, the pull can obtain its objects from the local
-repository using `.`, as the previous `git-fetch` is
-known to have already obtained and made available
-all the necessary objects.
-
-
-Pull of multiple branches from one repository using `.git/remotes` file::
+This updates (or creates, as necessary) branches `pu` and `tmp`
+in the local repository by fetching from the branches
+(respectively) `pu` and `maint` from the remote repository.
 +
-------------------------------------------------
-$ cat .git/remotes/origin
-URL: git://git.kernel.org/pub/scm/git/git.git
-Pull: master:origin
-Pull: +pu:pu
-Pull: maint:maint
-
-$ git checkout master
-$ git pull origin
-------------------------------------------------
+The `pu` branch will be updated even if it is does not
+fast-forward; the others will not be.
 +
-Here, a typical `.git/remotes/origin` file from a
-`git-clone` operation has been hand-modified to include
-the branch-mapping of additional remote and local
-heads directly.  A single `git-pull` operation while
-in the `master` branch will fetch multiple heads and
-merge the remote `origin` head into the current,
-local `master` branch.
+The final command then merges the newly fetched `tmp` into master.
 
 
 If you tried a pull which resulted in a complex conflicts and
@@ -112,7 +93,7 @@ gitlink:git-reset[1].
 
 SEE ALSO
 --------
-gitlink:git-fetch[1], gitlink:git-merge[1]
+gitlink:git-fetch[1], gitlink:git-merge[1], gitlink:git-repo-config[1]
 
 
 Author
-- 
1.5.0.rc0.gac28

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

[J. Bruce Fields]

On Mon, Jan 01, 2007 at 04:39:06PM -0500, J. Bruce Fields wrote:
> On Sun, Dec 31, 2006 at 05:44:37PM -0800, Junio C Hamano wrote:
> > How about doing this?  The difference this time around is that
> > if you have non-wildcard refspec listed first, which usually
> > is the case for people with established git workflow with
> > existing repositories, we use the old-and-proven rule to
> > merge the first set of refs.  An earlier round botched this
> > completely by basing the logic on lack of branch.*.merge,
> > which broke for many people.
> 
> Updated man page assuming that change; does this look any better?

Also, resend of the following patch:

--b.

[PATCH] Documentation: remove master:origin example from pull-fetch-param.txt

This is no longer a useful example.

Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
---
 Documentation/pull-fetch-param.txt |    4 ----
 1 files changed, 0 insertions(+), 4 deletions(-)

diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
index e852f41..8d4e950 100644
--- a/Documentation/pull-fetch-param.txt
+++ b/Documentation/pull-fetch-param.txt
@@ -39,10 +39,6 @@ checkout -b my-B remote-B`).  Run `git fetch` to keep track of
 the progress of the remote side, and when you see something new
 on the remote branch, merge it into your development branch with
 `git pull . remote-B`, while you are on `my-B` branch.
-The common `Pull: master:origin` mapping of a remote `master`
-branch to a local `origin` branch, which is then merged to a
-local development branch, again typically named `master`, is made
-when you run `git clone` for you to follow this pattern.
 +
 [NOTE]
 There is a difference between listing multiple <refspec>
-- 
1.5.0.rc0.gac28

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

[Luben Tuikov]

--- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> On Mon, Jan 01, 2007 at 04:39:06PM -0500, J. Bruce Fields wrote:
> > On Sun, Dec 31, 2006 at 05:44:37PM -0800, Junio C Hamano wrote:
> > > How about doing this?  The difference this time around is that
> > > if you have non-wildcard refspec listed first, which usually
> > > is the case for people with established git workflow with
> > > existing repositories, we use the old-and-proven rule to
> > > merge the first set of refs.  An earlier round botched this
> > > completely by basing the logic on lack of branch.*.merge,
> > > which broke for many people.
> > 
> > Updated man page assuming that change; does this look any better?
> 
> Also, resend of the following patch:
> 
> --b.
> 
> [PATCH] Documentation: remove master:origin example from pull-fetch-param.txt
> 
> This is no longer a useful example.
> 
> Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
> ---
>  Documentation/pull-fetch-param.txt |    4 ----
>  1 files changed, 0 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt
> index e852f41..8d4e950 100644
> --- a/Documentation/pull-fetch-param.txt
> +++ b/Documentation/pull-fetch-param.txt
> @@ -39,10 +39,6 @@ checkout -b my-B remote-B`).  Run `git fetch` to keep track of
>  the progress of the remote side, and when you see something new
>  on the remote branch, merge it into your development branch with
>  `git pull . remote-B`, while you are on `my-B` branch.
> -The common `Pull: master:origin` mapping of a remote `master`
> -branch to a local `origin` branch, which is then merged to a
> -local development branch, again typically named `master`, is made
> -when you run `git clone` for you to follow this pattern.

So is this no longer the case?

Can someone please bring me up to date?

What is going on?

    Luben



>  +
>  [NOTE]
>  There is a difference between listing multiple <refspec>
> -- 
> 1.5.0.rc0.gac28
> 
> 

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

[J. Bruce Fields]

On Mon, Jan 01, 2007 at 04:01:15PM -0800, Luben Tuikov wrote:
> --- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > -The common `Pull: master:origin` mapping of a remote `master`
> > -branch to a local `origin` branch, which is then merged to a
> > -local development branch, again typically named `master`, is made
> > -when you run `git clone` for you to follow this pattern.
> 
> So is this no longer the case?

Right; that mapping is no longer what git clone sets up for you.

> Can someone please bring me up to date?
> 
> What is going on?

The simplest way to understand the current behavior is probably to
install the latest git, read the git-clone man page, clone a new
repository, and take a look at it.

Remote branches are stored in separate namespaces under
.git/refs/remotes/, so that they don't muck up your view of your local
branches, and so git can enforce different policies for them (such as
forbidding committing to them).

--b.

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

[Theodore Tso]

On Mon, Jan 01, 2007 at 07:10:44PM -0500, J. Bruce Fields wrote:
> 
> The simplest way to understand the current behavior is probably to
> install the latest git, read the git-clone man page, clone a new
> repository, and take a look at it.

This should be mentioned in the 1.5 release notes --- that you won't
see a lot of the power the new git unless you create a new repository
using git-clone.  For example, the man page for git-branch says that
"git branch -r" will list remote branches won't print anything if the
repository was originally cloned using an older version of git.  

(I was using the version that shipped with Ubuntu Edgy before I
recently upgraded to the bleeding edge "next" branch so I could try
out the latest and greatest git features that was being discussed on
the mailing list.  :-)

						- Ted

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

[Luben Tuikov]

--- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> On Mon, Jan 01, 2007 at 04:01:15PM -0800, Luben Tuikov wrote:
> > --- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > > -The common `Pull: master:origin` mapping of a remote `master`
> > > -branch to a local `origin` branch, which is then merged to a
> > > -local development branch, again typically named `master`, is made
> > > -when you run `git clone` for you to follow this pattern.
> > 
> > So is this no longer the case?
> 
> Right; that mapping is no longer what git clone sets up for you.
> 
> > Can someone please bring me up to date?
> > 
> > What is going on?
> 
> The simplest way to understand the current behavior is probably to
> install the latest git, read the git-clone man page, clone a new
> repository, and take a look at it.
> 
> Remote branches are stored in separate namespaces under
> .git/refs/remotes/, so that they don't muck up your view of your local
> branches, and so git can enforce different policies for them (such as
> forbidding committing to them).

Smells like another "newbie" protection.

Let me understand, someone here installed git, didn't read the then
man page of git-clone/pull/fetch, screwed up their repo, and decided
to change established behavior.

Regardless, I think addressable (named) branch specs are the way to go.
This will as well, unify/reconcile remotes/ and local stuff, since
it is already implemented for remotes/ .

     Luben

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

[Junio C Hamano]

Luben Tuikov <ltuikov@yahoo.com> writes:

> --- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> ...
>> Remote branches are stored in separate namespaces under
>> .git/refs/remotes/, so that they don't muck up your view of your local
>> branches, and so git can enforce different policies for them (such as
>> forbidding committing to them).
>
> Smells like another "newbie" protection.
>
> Let me understand, someone here installed git, didn't read the then
> man page of git-clone/pull/fetch, screwed up their repo, and decided
> to change established behavior.

You smelled and understood wrongly in this case.  Another point
in separate-remote layout is that it makes it easier to interact
with more than one remotes, and we do not have to treat 'master'
and 'origin' as branch names any more specially than necessary.

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

[Luben Tuikov]

--- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> On Mon, Jan 01, 2007 at 04:01:15PM -0800, Luben Tuikov wrote:
> > --- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > > -The common `Pull: master:origin` mapping of a remote `master`
> > > -branch to a local `origin` branch, which is then merged to a
> > > -local development branch, again typically named `master`, is made
> > > -when you run `git clone` for you to follow this pattern.
> > 
> > So is this no longer the case?
> 
> Right; that mapping is no longer what git clone sets up for you.
> 
> > Can someone please bring me up to date?
> > 
> > What is going on?
> 
> The simplest way to understand the current behavior is probably to
> install the latest git, read the git-clone man page, clone a new
> repository, and take a look at it.

I don't like "learning by observation" when there is an
intention -- i.e. I'd rather see a well written justification
of the intentions and design, as opposed to "poke at the black
box and try to figure it out".

It's like learning math by trying to memorize the formulas
as opposed to knowing how to derive them and why they are
the way they are.

I'm expecting a well written man page on the new stuff
_compared_ to the old stuff, similarly to Junio's response
to this very same email.

    Luben


> 
> Remote branches are stored in separate namespaces under
> .git/refs/remotes/, so that they don't muck up your view of your local
> branches, and so git can enforce different policies for them (such as
> forbidding committing to them).
> 
> --b.
> 

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

[Junio C Hamano]

Luben Tuikov <ltuikov@yahoo.com> writes:

> --- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> ...
>> -The common `Pull: master:origin` mapping of a remote `master`
>> -branch to a local `origin` branch, which is then merged to a
>> -local development branch, again typically named `master`, is made
>> -when you run `git clone` for you to follow this pattern.
>
> So is this no longer the case?
>
> Can someone please bring me up to date?
>
> What is going on?

What's going on is clean-up towards v1.5.0-rc1 ;-).

 - 'git clone' does not create a file that has a line that looks
   like "Pull: master:origin" anywhere anymore.

 - 'git clone' also does not create the traditional "'master' is
   special and we map that to origin, others are mapped as is
   under refs/heads/, and we have to drop 'origin' from the
   remote side because that name we want to use to store their
   'master'" layout.

So after a clone, you would get:

	[remote "origin"]
        	url = ....
                fetch = refs/heads/*:refs/remotes/origin/*
        [branch "master"]
        	remote = origin
                merge = refs/heads/master

This configuration still causes "git pull" or "git pull origin"
while on "master" to fetch and store the remote side's master as
what you can refer to as 'origin' (because it expands to
'remotes/origin/HEAD' thanks to sha1_name.c::get_sha1_basic()),
and then merges that to your current branch, so there is no
change in the user experience in the big picture, but what is
created to achieve that effect is different from what was
described.

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

[Jakub Narebski]

Junio C Hamano wrote:

> So after a clone, you would get:
> 
>         [remote "origin"]
>                 url = ....
>                 fetch = refs/heads/*:refs/remotes/origin/*

By the way, I have thought that you would also get (to avoid nasty 
"we don't know which branch is first in glob")

                  fetch = refs/heads/master:refs/remotes/origin/master

or

                  fetch = refs/heads/master:refs/remotes/origin/HEAD

(if master was current branch)

>         [branch "master"]
>                 remote = origin
>                 merge = refs/heads/master

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

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

[Luben Tuikov]

--- Junio C Hamano <junkio@cox.net> wrote:
> What's going on is clean-up towards v1.5.0-rc1 ;-).
> 
>  - 'git clone' does not create a file that has a line that looks
>    like "Pull: master:origin" anywhere anymore.
> 
>  - 'git clone' also does not create the traditional "'master' is
>    special and we map that to origin, others are mapped as is
>    under refs/heads/, and we have to drop 'origin' from the
>    remote side because that name we want to use to store their
>    'master'" layout.
> 
> So after a clone, you would get:
> 
> 	[remote "origin"]
>         	url = ....
>                 fetch = refs/heads/*:refs/remotes/origin/*
>         [branch "master"]
>         	remote = origin
>                 merge = refs/heads/master
> 
> This configuration still causes "git pull" or "git pull origin"
> while on "master" to fetch and store the remote side's master as
> what you can refer to as 'origin' (because it expands to
> 'remotes/origin/HEAD' thanks to sha1_name.c::get_sha1_basic()),
> and then merges that to your current branch, so there is no
> change in the user experience in the big picture, but what is
> created to achieve that effect is different from what was
> described.

Ah, I see.  Thanks Junio.

... And this is why I see some objections as to what I'm proposing
because it extends too far the extension itself of the old
behavior. (See below.)

Questions:

What is the reasonining of defining branch.<name>.merge to point
to the "remote's setup"?  I would much, much rather stop the leak
of the remote's setup right at [remote] and contain it there,
while everything in [branch] would refer to local stuff.

So the above configuration would become:

 	[remote "origin"]
         	url = ....
                fetch = refs/heads/*:refs/remotes/origin/*
        [branch "master"]
         	remote = origin
# merge gives the place and name of the remote branch locally mapped
                merge = refs/heads/origin/master
# OR, better yet
# merge gives the name only of the remote branch to be merged
# the local mapping can be found from "remote = " above
                merge = master

The reasoning is that the remote's setup should only leak into
[remote] and no further.  I.e. [remote] is the only one concerned
with the mapping between the remote repo and the local repo.

Then, [branch] only talks about local relationships.  Now
since [branch] does refer to _where_ the local mapping resolves
to, i.e. the right hand part of `:', then there is a redundancy
in branch.<name>.merge, since branch.<name>.remote _does refer_
to [remote] where we can find where it is locally mapped.

Thus, by reducibility, branch.name.merge should only contain
a name.  Here is the dependency graph:

branch.name.merge <- (gives a local name)
      branch.name.remote <- (gives the remote)
            remote.rname.fetch <- (gives the remote:local name mapping)
                   remote.rname.url (gives the URL).

Now as to what I'm talking about, should be able to be had with:

     [remote "parent"]
           url = .
           fetch = :
     [branch "A"]
           remote = parent
           merge = master
     [branch "B"]
           remote = parent
           merge = A
     [branch "C"]
           remote = parent
           merge = B

   Luben

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

[Junio C Hamano]

Luben Tuikov <ltuikov@yahoo.com> writes:

> Questions:
>
> What is the reasonining of defining branch.<name>.merge to point
> to the "remote's setup"?

See list archives.  

Because you are not required to use remote tracking branches.
By the way, I think we allow the name of the remote tracking
branch as well, but we do not advertise it -- always using
remote's name consistently is much less confusing.

> The reasoning is that the remote's setup should only leak into
> [remote] and no further.  I.e. [remote] is the only one concerned
> with the mapping between the remote repo and the local repo.

No.  Remote is not about mapping -- if mapping is there you can
talk about it, but that is optional.

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

[Jakub Narebski]

Junio C Hamano wrote:

> Luben Tuikov <ltuikov@yahoo.com> writes:
> 
>> Questions:
>>
>> What is the reasonining of defining branch.<name>.merge to point
>> to the "remote's setup"?
> 
> See list archives.  
> 
> Because you are not required to use remote tracking branches.
> By the way, I think we allow the name of the remote tracking
> branch as well, but we do not advertise it -- always using
> remote's name consistently is much less confusing.

If  remember correctly there were added some magic which makes
git search on pull first remote branches (to allow to pull
without tracking branches), then tracking branches. This I think
supercedes alternate proposal of using branch.<name>.mergeLocal.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

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

[Luben Tuikov]

--- Junio C Hamano <junkio@cox.net> wrote:
> Luben Tuikov <ltuikov@yahoo.com> writes:
> 
> > Questions:
> >
> > What is the reasonining of defining branch.<name>.merge to point
> > to the "remote's setup"?
> 
> See list archives.  
> 
> Because you are not required to use remote tracking branches.

Then why does it point to the _remote_ mapping?  One shouldn't
care what it is, and how it looks in the remote repo.  That is
handled by [remote].  In [branch] I shouldn't have to have any
absolute references, i.e. branch.<name>.remote points to [remote],
and branch.<name>.merge should only give a _branch_ name,
whose remote-to-local mapping (which preserves the branch name)
can be found by dereferencing branch.<name>.remote to get to
remote.<rname>.fetch.

Think of it as DB schema normalization.

     Luben


> By the way, I think we allow the name of the remote tracking
> branch as well, but we do not advertise it -- always using
> remote's name consistently is much less confusing.
> 
> > The reasoning is that the remote's setup should only leak into
> > [remote] and no further.  I.e. [remote] is the only one concerned
> > with the mapping between the remote repo and the local repo.
> 
> No.  Remote is not about mapping -- if mapping is there you can
> talk about it, but that is optional.
> 
> 

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

[Jakub Narebski]

Luben Tuikov wrote:

> --- Junio C Hamano <junkio@cox.net> wrote:
>> Luben Tuikov <ltuikov@yahoo.com> writes:
>> 
>>> Questions:
>>>
>>> What is the reasonining of defining branch.<name>.merge to point
>>> to the "remote's setup"?
>> 
>> See list archives.  
>> 
>> Because you are not required to use remote tracking branches.
> 
> Then why does it point to the _remote_ mapping?  One shouldn't
> care what it is, and how it looks in the remote repo.  That is
> handled by [remote].  In [branch] I shouldn't have to have any
> absolute references, i.e. branch.<name>.remote points to [remote],
> and branch.<name>.merge should only give a _branch_ name,
> whose remote-to-local mapping (which preserves the branch name)
> can be found by dereferencing branch.<name>.remote to get to
> remote.<rname>.fetch.

Once again: if you _don't_ have _local_ tracking branch, so you _must_
use _remote_ name.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

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

[Junio C Hamano]

Luben Tuikov <ltuikov@yahoo.com> writes:

> --- Junio C Hamano <junkio@cox.net> wrote:
>> Luben Tuikov <ltuikov@yahoo.com> writes:
>> 
>> > Questions:
>> >
>> > What is the reasonining of defining branch.<name>.merge to point
>> > to the "remote's setup"?
>> 
>> See list archives.  
>> 
>> Because you are not required to use remote tracking branches.
>
> Then why does it point to the _remote_ mapping?  One shouldn't

Because [remote] is NOT about mapping.  It asks the fetch
mechanism to fetch from that remote, so the primary thing you
should look at is .url, not RHS of colon on .fetch lines.  Use
of tracking branches is strictly optional.

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

[Luben Tuikov]

--- Junio C Hamano <junkio@cox.net> wrote:
> 
> Because [remote] is NOT about mapping.  It asks the fetch
> mechanism to fetch from that remote, so the primary thing you
> should look at is .url, not RHS of colon on .fetch lines.  Use
> of tracking branches is strictly optional.

Remote
------

Please help me understand.  Here is a sample remote from
an actual repo (actual names changed):

[remote "origin"]
        url = http://blah/bleah.git
        fetch = +refs/heads/*:refs/remotes/origin/*

This basically says: "Get it" from such and such url, where
on the repo at that url, i.e. the remote side, you will
find stuff in "refs/heads/", and when you get it here, locally,
put it in refs/remotes/origin/.

Now if this isn't a mapping, then please can someone
explain to me what a "mapping" is?

The "fetch = <remote>:<local>" is inherently a mapping,
its syntax dictates it, as does the actual actions
it performs: "fetch" from "remote" and "put in local <local>".

Branch
------

Here is an actual example:

[branch "branchA"]
        remote = origin
        merge = refs/heads/branchA

Yeah, but by default "refs/heads/branchA" doesn't exist (see
my previous email).  It doesn't have to, since it specifies
the "remote part", but that has already been handled by
"[remote]".

Unless of course "[branch "..."]" specifies the _remote_ branch
being tracked in refs/remotes/origin.  Is this the case.

Does "[branch]" apply to local branches too?  If so,
then what happens when refs/heads/branchA does exist and is
the same as the one it describes -- i.e. completely old behavior.

Thanks,
    Luben

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

[Junio C Hamano]

Luben Tuikov <ltuikov@yahoo.com> writes:

> --- Junio C Hamano <junkio@cox.net> wrote:
>> 
>> Because [remote] is NOT about mapping.  It asks the fetch
>> mechanism to fetch from that remote, so the primary thing you
>> should look at is .url, not RHS of colon on .fetch lines.  Use
>> of tracking branches is strictly optional.
>
> Remote
> ------
>
> Please help me understand.  Here is a sample remote from
> an actual repo (actual names changed):
>
> [remote "origin"]
>         url = http://blah/bleah.git
>         fetch = +refs/heads/*:refs/remotes/origin/*
>
> This basically says: "Get it" from such and such url, where
> on the repo at that url, i.e. the remote side, you will
> find stuff in "refs/heads/", and when you get it here, locally,
> put it in refs/remotes/origin/.

        [remote "origin"]
                url = http://blah/blah.git
                fetch = refs/heads/master

is also fine.  The point is that you do not have to use tracking
branches.  ", and when you get it here, ..." part is optional.

> Branch
> ------
>
> Here is an actual example:
>
> [branch "branchA"]
>         remote = origin
>         merge = refs/heads/branchA
>
> Yeah, but by default "refs/heads/branchA" doesn't exist (see
> my previous email).  It doesn't have to, since it specifies
> the "remote part", but that has already been handled by
> "[remote]".

Obviously fetch needs to handle the remote part because that is
the only name it exists at the remote.  branch.*.merge is used
by pull, not fetch, and fetch communicates with pull by using
the remote name, because use of local tracking branches is
optional.

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

[Junio C Hamano]

Junio C Hamano <junkio@cox.net> writes:

> Luben Tuikov <ltuikov@yahoo.com> writes:
>
>> --- Junio C Hamano <junkio@cox.net> wrote:
>>> 
>>> Because [remote] is NOT about mapping.  It asks the fetch
>>> mechanism to fetch from that remote, so the primary thing you
>>> should look at is .url, not RHS of colon on .fetch lines.  Use
>>> of tracking branches is strictly optional.
>>
>> [remote "origin"]
>>         url = http://blah/bleah.git
>>         fetch = +refs/heads/*:refs/remotes/origin/*
>>
>> This basically says: "Get it" from such and such url, where
>> on the repo at that url, i.e. the remote side, you will
>> find stuff in "refs/heads/", and when you get it here, locally,
>> put it in refs/remotes/origin/.
>
>         [remote "origin"]
>                 url = http://blah/blah.git
>                 fetch = refs/heads/master
>
> is also fine.  The point is that you do not have to use tracking
> branches.  ", and when you get it here, ..." part is optional.

In other words, remote.*.fetch could be spelled as mapping to
cause them locally stored in tracking branches, but the storing
in tracking branches is merely a side effect of a fetch, not the
primary one.  The primary effect is to fetch the necessary
objects and leave what was fetched in .git/FETCH_HEAD to
communicate with later 'git pull'.  The side effect is optional,
so is spelling remote.*.fetch as a mapping.

>> Yeah, but by default "refs/heads/branchA" doesn't exist (see
>> my previous email).  It doesn't have to, since it specifies
>> the "remote part", but that has already been handled by
>> "[remote]".
>
> Obviously fetch needs to handle the remote part because that is
> the only name it exists at the remote.  branch.*.merge is used
> by pull, not fetch, and fetch communicates with pull by using
> the remote name, because use of local tracking branches is
> optional.

In other words, the remote name is the only thing that can be
used between fetch and pull to communicate.  Fetch tells pull "I
fetched these from the remote", and pull uses that information
to make a merge, and the merge comment says "this merges the
branch xyz from that repository", using the 'xyz' name used at
the remote side, not your local tracking branch, which you may
or may not be using.

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

[Luben Tuikov]

--- Junio C Hamano <junkio@cox.net> wrote:
> Junio C Hamano <junkio@cox.net> writes:
> 
> > Luben Tuikov <ltuikov@yahoo.com> writes:
> >
> >> --- Junio C Hamano <junkio@cox.net> wrote:
> >>> 
> >>> Because [remote] is NOT about mapping.  It asks the fetch
> >>> mechanism to fetch from that remote, so the primary thing you
> >>> should look at is .url, not RHS of colon on .fetch lines.  Use
> >>> of tracking branches is strictly optional.
> >>
> >> [remote "origin"]
> >>         url = http://blah/bleah.git
> >>         fetch = +refs/heads/*:refs/remotes/origin/*
> >>
> >> This basically says: "Get it" from such and such url, where
> >> on the repo at that url, i.e. the remote side, you will
> >> find stuff in "refs/heads/", and when you get it here, locally,
> >> put it in refs/remotes/origin/.
> >
> >         [remote "origin"]
> >                 url = http://blah/blah.git
> >                 fetch = refs/heads/master
> >
> > is also fine.  The point is that you do not have to use tracking
> > branches.  ", and when you get it here, ..." part is optional.
> 
> In other words, remote.*.fetch could be spelled as mapping to
> cause them locally stored in tracking branches, but the storing
> in tracking branches is merely a side effect of a fetch, not the
> primary one.  The primary effect is to fetch the necessary
> objects and leave what was fetched in .git/FETCH_HEAD to
> communicate with later 'git pull'.  The side effect is optional,
> so is spelling remote.*.fetch as a mapping.

Oh ok -- I forgot about .git/FETCH_HEAD.

> >> Yeah, but by default "refs/heads/branchA" doesn't exist (see
> >> my previous email).  It doesn't have to, since it specifies
> >> the "remote part", but that has already been handled by
> >> "[remote]".
> >
> > Obviously fetch needs to handle the remote part because that is
> > the only name it exists at the remote.  branch.*.merge is used
> > by pull, not fetch, and fetch communicates with pull by using
> > the remote name, because use of local tracking branches is
> > optional.
> 
> In other words, the remote name is the only thing that can be
> used between fetch and pull to communicate.  Fetch tells pull "I
> fetched these from the remote", and pull uses that information
> to make a merge, and the merge comment says "this merges the
> branch xyz from that repository", using the 'xyz' name used at
> the remote side, not your local tracking branch, which you may
> or may not be using.

Ok.

    Luben

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

[Luben Tuikov]

--- Junio C Hamano <junkio@cox.net> wrote:
> Luben Tuikov <ltuikov@yahoo.com> writes:
> 
> > --- Junio C Hamano <junkio@cox.net> wrote:
> >> 
> >> Because [remote] is NOT about mapping.  It asks the fetch
> >> mechanism to fetch from that remote, so the primary thing you
> >> should look at is .url, not RHS of colon on .fetch lines.  Use
> >> of tracking branches is strictly optional.
> >
> > Remote
> > ------
> >
> > Please help me understand.  Here is a sample remote from
> > an actual repo (actual names changed):
> >
> > [remote "origin"]
> >         url = http://blah/bleah.git
> >         fetch = +refs/heads/*:refs/remotes/origin/*
> >
> > This basically says: "Get it" from such and such url, where
> > on the repo at that url, i.e. the remote side, you will
> > find stuff in "refs/heads/", and when you get it here, locally,
> > put it in refs/remotes/origin/.
> 
>         [remote "origin"]
>                 url = http://blah/blah.git
>                 fetch = refs/heads/master
> 
> is also fine.  The point is that you do not have to use tracking
> branches.  ", and when you get it here, ..." part is optional.

Ok. So then in this case "fetch = refs/heads/master" describes
.git/refs/heads/master or something else?

If it does, then this is a local map.

I guess this is the case where one wants to automate
"git-pull . OtherBranch", but shouldn't this be handled
by [branch], i.e. the "merge" part of [branch].

> > Branch
> > ------
> >
> > Here is an actual example:
> >
> > [branch "branchA"]
> >         remote = origin
> >         merge = refs/heads/branchA
> >
> > Yeah, but by default "refs/heads/branchA" doesn't exist (see
> > my previous email).  It doesn't have to, since it specifies
> > the "remote part", but that has already been handled by
> > "[remote]".
> 
> Obviously fetch needs to handle the remote part because that is
> the only name it exists at the remote.  branch.*.merge is used
> by pull, not fetch, and fetch communicates with pull by using
> the remote name, because use of local tracking branches is
> optional.

Does this mean that "fetch = <remote>:" is legal?  Shouldn't the
RHS always exist?  Is the RHS of "fetch = :" what you mean
by local tracking branches?

    Luben

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

[Junio C Hamano]

Luben Tuikov <ltuikov@yahoo.com> writes:

>>         [remote "origin"]
>>                 url = http://blah/blah.git
>>                 fetch = refs/heads/master
>> 
>> is also fine.  The point is that you do not have to use tracking
>> branches.  ", and when you get it here, ..." part is optional.
>
> Ok. So then in this case "fetch = refs/heads/master" describes
> .git/refs/heads/master or something else?

It names http://blah/blah.git/refs/heads/master (unless blah.git
repository uses packed refs then has pruned the loose refs).

> If it does, then this is a local map.

No, it is just a list of remote refs (one element list because
there is only one "fetch =" line).

> Does this mean that "fetch = <remote>:" is legal?  Shouldn't the
> RHS always exist?

Documentation/pull-fetch-param.txt

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

[Luben Tuikov]

--- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> On Sun, Dec 31, 2006 at 05:44:37PM -0800, Junio C Hamano wrote:
> > How about doing this?  The difference this time around is that
> > if you have non-wildcard refspec listed first, which usually
> > is the case for people with established git workflow with
> > existing repositories, we use the old-and-proven rule to
> > merge the first set of refs.  An earlier round botched this
> > completely by basing the logic on lack of branch.*.merge,
> > which broke for many people.
> 
> Updated man page assuming that change; does this look any better?
> 
> --b.
> 
> [PATCH] Documentation: update git-pull.txt for new clone behavior
> 
> Update examples, stop using branch named "origin" as an example.
> Remove large example of use of remotes; that particular case is
> nicely automated by default, so it's not so pressing to explain, and
> we can refer to git-repo-config for the details.
> 
> Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
> ---
>  Documentation/git-pull.txt |   69 ++++++++++++++++----------------------------
>  1 files changed, 25 insertions(+), 44 deletions(-)
> 
> diff --git a/Documentation/git-pull.txt b/Documentation/git-pull.txt
> index 2a5aea7..13be992 100644
> --- a/Documentation/git-pull.txt
> +++ b/Documentation/git-pull.txt
> @@ -37,17 +37,27 @@ EXAMPLES
>  --------
>  
>  git pull, git pull origin::
> -	Fetch the default head from the repository you cloned
> -	from and merge it into your current branch.
> -
> -git pull -s ours . obsolete::
> -	Merge local branch `obsolete` into the current branch,
> -	using `ours` merge strategy.
> +	Update the remote-tracking branches 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, but the choice is
> +	determined by the branch.<name>.remote and
> +	branch.<name>.merge options; see gitlink:git-repo-config[1]
> +	for details.
> +
> +git pull origin next::

No.

> +	Merge into the current branch the remote branch `next`;

So, "origin" now means "current branch".

NACK!

   Luben


> +	leaves a copy of `next` temporarily in FETCH_HEAD, but
> +	does not update any remote-tracking branches.
>  
>  git pull . fixes enhancements::
>  	Bundle local branch `fixes` and `enhancements` on top of
>  	the current branch, making an Octopus merge.
>  
> +git pull -s ours . obsolete::
> +	Merge local branch `obsolete` into the current branch,
> +	using `ours` merge strategy.
> +
>  git pull --no-commit . maint::
>  	Merge local branch `maint` into the current branch, but
>  	do not make a commit automatically.  This can be used
> @@ -61,48 +71,19 @@ release/version name would be acceptable.
>  Command line pull of multiple branches from one repository::
>  +
>  ------------------------------------------------
> -$ cat .git/remotes/origin
> -URL: git://git.kernel.org/pub/scm/git/git.git
> -Pull: master:origin
> -
>  $ git checkout master
> -$ git fetch origin master:origin +pu:pu maint:maint
> -$ git pull . origin
> +$ git fetch origin +pu:pu maint:tmp
> +$ git pull . tmp
>  ------------------------------------------------
>  +
> -Here, a typical `.git/remotes/origin` file from a
> -`git-clone` operation is used in combination with
> -command line options to `git-fetch` to first update
> -multiple branches of the local repository and then
> -to merge the remote `origin` branch into the local
> -`master` branch.  The local `pu` branch is updated
> -even if it does not result in a fast forward update.
> -Here, the pull can obtain its objects from the local
> -repository using `.`, as the previous `git-fetch` is
> -known to have already obtained and made available
> -all the necessary objects.
> -
> -
> -Pull of multiple branches from one repository using `.git/remotes` file::
> +This updates (or creates, as necessary) branches `pu` and `tmp`
> +in the local repository by fetching from the branches
> +(respectively) `pu` and `maint` from the remote repository.
>  +
> -------------------------------------------------
> -$ cat .git/remotes/origin
> -URL: git://git.kernel.org/pub/scm/git/git.git
> -Pull: master:origin
> -Pull: +pu:pu
> -Pull: maint:maint
> -
> -$ git checkout master
> -$ git pull origin
> -------------------------------------------------
> +The `pu` branch will be updated even if it is does not
> +fast-forward; the others will not be.
>  +
> -Here, a typical `.git/remotes/origin` file from a
> -`git-clone` operation has been hand-modified to include
> -the branch-mapping of additional remote and local
> -heads directly.  A single `git-pull` operation while
> -in the `master` branch will fetch multiple heads and
> -merge the remote `origin` head into the current,
> -local `master` branch.
> +The final command then merges the newly fetched `tmp` into master.
>  
>  
>  If you tried a pull which resulted in a complex conflicts and
> @@ -112,7 +93,7 @@ gitlink:git-reset[1].
>  
>  SEE ALSO
>  --------
> -gitlink:git-fetch[1], gitlink:git-merge[1]
> +gitlink:git-fetch[1], gitlink:git-merge[1], gitlink:git-repo-config[1]
>  
>  
>  Author
> -- 
> 1.5.0.rc0.gac28
> 
> 

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

[J. Bruce Fields]

On Mon, Jan 01, 2007 at 03:59:44PM -0800, Luben Tuikov wrote:
> --- "J. Bruce Fields" <bfields@fieldses.org> wrote:
> > +git pull origin next::
> 
> No.
> 
> > +	Merge into the current branch the remote branch `next`;
> 
> So, "origin" now means "current branch".

No, "origin" refers to the remote repository that you originally cloned
from.

Pulls always merge into the current branch.  So it wouldn't make sense
to specify the current branch on the command line.

--b.

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

[Junio C Hamano]

"J. Bruce Fields" <bfields@fieldses.org> writes:

> On Mon, Jan 01, 2007 at 03:59:44PM -0800, Luben Tuikov wrote:
>> --- "J. Bruce Fields" <bfields@fieldses.org> wrote:
>> > +git pull origin next::
>> 
>> No.
>> 
>> > +	Merge into the current branch the remote branch `next`;
>> 
>> So, "origin" now means "current branch".
>
> No, "origin" refers to the remote repository that you originally cloned
> from.
>
> Pulls always merge into the current branch.  So it wouldn't make sense
> to specify the current branch on the command line.

I was also somewhat confused by these examples.  I think the
description is fine as long as we make it clear that they are
not meant to describe what an advanced user _could_ do with
various customizations, but to describe what happens with the
default configuration set up by git-clone.