Re: [PATCH 1/3] fetch: add --allow-local option

Felipe Contreras <felipe.contreras@gmail.com> writes:

Because the book was written by those who did not know about its use, and I do not necessarily think it is their fault. Our own documentation can use updates.

Patches to the tutorial to explain (you can refer to postings by people who discuss on public "users help other users" site like stackoverflow) the equivalence of the "git pull" == "git fetch" followed by "git merge FETCH_HEAD" better than it currently does is welcome. IIUC, ProGit is maintained in public and you can send patches to it, too.

Users of stackoverflow seem to know about and how to use FETCH_HEAD:

    http://stackoverflow.com/questions/9237348/what-does-fetch-head-in-git-mean
    http://stackoverflow.com/questions/11478558/fetch-head-not-updating-after-git-fetch

and they expect exactly what I described in the earlier message. If you ask your search engine about "FETCH_HEAD", you would find other real-world use of it as well (one of them I found was about somebody requesting to teach TortoiseGit to offer FETCH_HEAD as a candate to be merged, IIRC).

Incidentally, this discussion on our own list

    http://thread.gmane.org/gmane.comp.version-control.git/42788/focus=42798

shows that I was originally not very keen to defend "fetch, then inspect with log FETCH_HEAD, and then finally merge" workflow to keep working myself [*1*], which is somewhat funny.

So, no, it is not my whim, but people do depend on "git fetch" that updates FETCH_HEAD to what is to be merged with "git pull".

You seem to be incapable to understand what backward compatibility is. It is not about "keep only what I use myself, I think others should use, and/or I understand, working, and destroy everything else".

Also your "special-case local repository and fetch from 'origin'" breaks down once your users need to work on a project with subsystem maintainers.

Imagine one clones from me (i.e. git.git is her upstream), and forks her fh-octopus branch out of her master branch ("git clone" arranges the latter to be a fork of origin/master taken from me). She helps git-svn and has Eric's repository as her "git-svn" remote (because my tree lags behind Eric's tree with respect to git-svn). Her local git-svn branch is a fork of Eric's master, and she has her svn-ext branch that is a fork of it [*2*].

    git clone git://git.kernel.org/pub/scm/git/git.git git
    cd git

    git checkout -t -b fh-octopus master
    git remote add git-svn git://git.bogomips.org/git-svn.git/
    git checkout -t -b git-svn git-svn/master
    git checkout -t -b svn-ext git-svn

She has four local branches, master, fh-octopus, git-svn, and svn-ext. Is this a too-contrived example? I do not think so.

On any of these branches, she can say

    git pull [--rebase]

without having to be constantly aware of what branch (either remote or local) the work on her current branch builds on. Like some people in the thread $gmane/42788 discussion, she may prefer to do the same integration with "first fetch, inspect and then integrate" workflow, relying on the equivalence "git pull" == "git fetch" + "git merge/rebase":

    git fetch
    git log ..FETCH_HEAD
    git merge FETCH_HEAD

But when she does this:

    git checkout fh-octopus
    git fetch

the "git fetch" does not fetch from me (i.e. her 'origin').

Would she be unhappy?

I agree that it could be argued so.

After all, she is working on a topic that is eventually based on my 'master' and the only reason she forked from her 'master' is because she may have other changes of her own on her 'master' that are not necessarily related to her fh-octopus topic. She wants her "git log @{u}.." not to show those unrelated changes on her 'master', but wants to rebase against her 'master'.

Because her @{u} does not refer to 'origin/master' taken from me (it refers to her local 'master'), however, even if we change "git fetch" to fetch from 'origin', what "git log ..@{u}" shows does not change, so the only "improvement" is that it does not trigger "I said 'git fetch' but it did not fetch anything? Did I make some mistake?" confusion.

Is that lack of confusion a big enough improvement, or is it easy enough for her to realize that what she wanted to inspect was what I've been doing in the meantime and run "git fetch origin"?

I know you would say it is an improvement; I am on the fence in the sense that no confusion is better than confusion, but that is a qualified "on the fence". I do not mind it fixed as long as the confusion avoidance does not regress other aspects of the operation we have kept working for people.

But more importantly, what should happen when she is working on her svn-ext branch?

    git checkout svn-ext
    git fetch

This does not fetch from me (i.e. her 'origin'), either. If this fetched from me, would she be happier?

It could be argued that it might be better if it fetched from Eric; after all she is working on svn-ext that eventually reaches Eric's tree. But fetching from me while she is working on svn-ext does not make any sense at all in her set-up, does it?

As I already said, I am OK with an enhancement that does (an equivalent of) the following:

 - Teach "git fetch --no-fetch-head <any args>" an option that
   causes it to do everything "git fetch <any args>" would do,
   except that in that mode, it does not touch FETCH_HEAD at all
   (the "--append" option that changes the behaviour of "git fetch"
   to only change what happens to FETCH_HEAD can be thought of a
   precedent).

 - Only when 'git fetch' (with no parameters, i.e. relies on
   configured defaults) is to fetch from '.':

   - First internally fork and run "git fetch --no-fetch-head
     <remote>" from the <remote> found by the following loop:

    - Set a variable B to the name of the current branch 
    - while branch.B.remote is the local repository:
      - assign the branch the branch B forked from,
        i.e. branch.B.merge, to variable B
    - branch.B.remote is the first remote repository in the fork
      ancestry chain.  That is the <remote> we are looking for.

   - Then do the usual 'git fetch' against the local repository,
     leaving what is to be merged in FETCH_HEAD as usual.

 - (optional) make the second "special case" opt-in, as people who
   have known Git may be upset when their "git pull" that they know
   would go to local repository touches network.  I do not think it
   is a huge deal, though, and that is why I marked it as optional.

I think that would alleviate the puzzlement some people may feel when they run 'git fetch' on a branch that integrates with their local branch, and sees no objects are transferred. It would do so without breaking anything.

Anything that breaks the "pull=fetch+merge" equivalence is not acceptable and no loud repeating from you will change that, with or without patches.

We owe at least that much to the people who asked us to keep it working over time and those who responded to them by working on maintaining it over time.

[Footnotes]

*1* Back then, FETCH_HEAD did not have the commit to be merged
    necessarily on the first line, so it was not very easy to work
    with it.  But that was fixed by 96890f4c428e (write first
    for-merge ref to FETCH_HEAD first, 2011-12-26), has been with us
    since v1.7.9, and the fix was not made by me, but Joey Hess.

*2* The invariant "git pull <fetch params>" == "git fetch <the same
    fetch params>" + "git merge FETCH_HEAD" (for any <fetch params>,
    including empty) has been true forever, and over time we made
    sure it hold true when we introduced new features because people
    depended on it, with commmits like these:

     - 85295a52e683 (git-merge: Put FETCH_HEAD data in merge commit
       message, 2007-03-22)

     - 96890f4c428e (write first for-merge ref to FETCH_HEAD first,
       2011-12-26)

    A remaining known bug is when the pull is to create an octopus,
    because "git merge FETCH_HEAD" currently can resolve FETCH_HEAD
    as only one commit.  The fh-octopus topic would extend the itch
    these two fixes started to scratch by teaching "git merge" to
    expand FETCH_HEAD into all commits that are not marked as
    not-for-merge to finish scratching that itch.

    svn-ext may teach git-svn to express a svn external as a git
    submodule.