RFC for 1.7: Do not checkout -b master origin/master on clone

RFC for 1.7: Do not checkout -b master origin/master on clone

[Michael J Gruber]

One common source of confusion for newcomers is the fact that master is
given such a special treatment in git. While it is certainly okay and
helpful to set up a default branch in a new repository (git init) it is
not at all clear why it should be treated specially in any other
situation, such as:

- Why is master the only local branch which git clone sets up (git
checkout -b master origin/master)?

- Why does git svn set up a local branch with an svn upstream which is
determined by latest svn commit at the time of the first git svn fetch?

This behaviour not only is hard to justify; in fact it gives users a
completely wrong impression: by pretending that master is special, but
also by hiding core concepts (distinguishing local/remote branches,
detached heads) from the user at a point where that very hiding leads to
confusion.

Under the hood, it is of course HEAD which is given special treatment
(and which in the majority of repos points to master), and git clone
sets up a local branch according to HEAD (and does some other guess work
when cloning bare repos), which means that git clone shows the same
"random" behaviour which git svn clone does: Which local branch is set
up by default depends on the current value of HEAD/most recent commit at
the time of the cloning operation.

So, I suggest that starting with git 1.7:

- git clone does not set up any local branches at all
- git svn fetch does not set up any local branches at all

Ducking under my desk...
Michael

Re: RFC for 1.7: Do not checkout -b master origin/master on clone

[Santi Béjar]

2009/8/11 Michael J Gruber <git@drmicha.warpmail.net>:
> One common source of confusion for newcomers is the fact that master is
> given such a special treatment in git. While it is certainly okay and
> helpful to set up a default branch in a new repository (git init) it is
> not at all clear why it should be treated specially in any other
> situation, such as:
>
> - Why is master the only local branch which git clone sets up (git
> checkout -b master origin/master)?

Because master is the default branch in the remote repository?

[...]

> This behaviour not only is hard to justify; in fact it gives users a
> completely wrong impression: by pretending that master is special,

It is not hard to justify (the git clone behavior). master is not
special, it is just the default branch, but you can change it changing
the HEAD symlink.

> but
> also by hiding core concepts (distinguishing local/remote branches,
> detached heads) from the user at a point where that very hiding leads to
> confusion.
>
> Under the hood, it is of course HEAD which is given special treatment
> (and which in the majority of repos points to master), and git clone
> sets up a local branch according to HEAD (and does some other guess work
> when cloning bare repos), which means that git clone shows the same
> "random" behaviour which git svn clone does: Which local branch is set
> up by default depends on the current value of HEAD/most recent commit at
> the time of the cloning operation.

It's not random. And please don't mix the "git clone" and "git svn" case.

> So, I suggest that starting with git 1.7:
>
> - git clone does not set up any local branches at all

I think you should first think if this is going to really help
newcomers. I think this would be worst.

Instead of "why only 'master'?" the question will be "why I don't get
any files in the workdir?"

"git clone checks out the default branch, and this is 'master' by
default" is not that hard.

HTH,
Santi

Re: RFC for 1.7: Do not checkout -b master origin/master on clone

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> One common source of confusion for newcomers is the fact that master is
> given such a special treatment in git. While it is certainly okay and
> helpful to set up a default branch in a new repository (git init) it is
> not at all clear why it should be treated specially in any other
> situation, such as:
>
> - Why is master the only local branch which git clone sets up (git
> checkout -b master origin/master)?

As you know it is not strictly "master".  It is the primary branch at the
cloned repository, which by convention is master", but whatever remote end
points at with its HEAD.

We check out that primary branch to make it easy for people to work with
the simplest kind of CVS/SVN-like settings, which I suspect is 99% of
peoples' projects.  Single "trunk" that is checked out immediately after
cloning from a distribution point (read: a bare repository) ready to be
used.

> - Why does git svn set up a local branch with an svn upstream which is
> determined by latest svn commit at the time of the first git svn fetch?

I do not have comments on design decisions in git-svn, other than trusting
that Eric would exercise good design tastes to make things coherent with
the git native workflow when the consistency makes sense.

> ..., and git clone
> sets up a local branch according to HEAD (and does some other guess work
> when cloning bare repos), which means that git clone shows the same
> "random" behaviour...

It is because you are cloning from a repository that is used actively to
build new history, flipping the HEAD left and right.  That is where the
randomness comes from.  IOW, a repository with an active work tree.

If you are cloning because you have your own private working area and you
would want to get another private working area to work simultaneously, you
have "clone -n && checkout -t origin/whatever".  Also if you are doing
this on a local machine (which is somewhat common), there is new-workdir
script in contrib/.  But this is _not_ the most common case we should
optimize the usability of "clone" for.

Re: RFC for 1.7: Do not checkout -b master origin/master on clone

[Eric Wong]

Junio C Hamano <gitster@pobox.com> wrote:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> > - Why does git svn set up a local branch with an svn upstream which is
> > determined by latest svn commit at the time of the first git svn fetch?
> 
> I do not have comments on design decisions in git-svn, other than trusting
> that Eric would exercise good design tastes to make things coherent with
> the git native workflow when the consistency makes sense.

Using 'trunk' (if available) as the master on new fetches does probably
make more sense based on the complaints I've gotten.  At the time,
several projects I cared about did almost all their work in branches and
trunk would go untouched for months....  These days most projects I care
about are already using git :)

-- 
Eric Wong

Re: RFC for 1.7: Do not checkout -b master origin/master on clone

[Matthieu Moy]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> - git clone does not set up any local branches at all
> - git svn fetch does not set up any local branches at all

If you don't set up a local branch, it means either

- You start with a detached HEAD, or
- You start with no working tree at all.

In both cases, you introduce more trouble for the beginner, just more
notions to learn before being able to do the very first step.

And you also break a good property of Git: in Git, you can use the
"one repo per branch" or the "multiple branches in a repository" the
way you want.

Personnally, I rarely have more than one branch for me (but I
appreciate very much having one branch per developer). And this way, I
can just forget that Git has multiple branches in a repo. When I want
to work on a project, I clone it, I hack, I commit, and then I
send the result (git push, git svn dcommit, git send-email, depending
on the project). In this workflow, I almost never have to use "git
branch", "git checkout", "git merge", it works, and Git does the right
thing for me.

-- 
Matthieu