Difficulties in advertising a new branch to git newbies

From: Carl Worth <cworth@cworth.org>
Date: 2007-01-31 07:13:26
So here's a scenario I'm in right now. A user of my software reported a
bug. I put together some patches to fix the bug and pushed them out as
a new branch "proposed-fix" that I'd like the user to test.

I'm trying to let the user know about the new branch, but I have some
users that know nothing about git. So I'm going to spell things out
fairly carefully, (which I'm glad to do). I also don't know how recent
a version of git the user has, (for example if clone will give
separate remotes or not).

Also, these users are glad to follow instructions, but they're really
interested in just testing the fix I'm offering, and not interested in
getting involved in a git tutorial just yet. (Though, I'd be quite
happy if they found this a gentle and enjoyable introduction to git).

I'm finding that the instructions I'm having to write are much more
complicated than I would like them to be. And some of this is due to
incompatibility between git 1.5 and previous versions. I would be glad
to see improvements to my instructions, (or improvements to git to
allow my instructions to be simpler).

Here's what I've done historically:

	I've published a new "proposed-fix" that I'd like you to
	test. You can obtain this code as follows:

		git clone git://git.project.org/~cworth/project
		cd project
		git checkout -b build proposed-fix

	or alternately, if you've already got a clone of the project
	around, just do:

		git fetch git://git.project.org/~cworth/project proposed-fix:proposed-fix
		git checkout -b build proposed-fix

The things I haven't liked in the above are:

	1. The doubled-up "branch:branch" thing in git-fetch, which
           just plain looks awkward. Yes, it's common for "git pull"
           to fetch something and not store it in any branch, but it
           seems that it could ask for that behavior explicitly and we
           could make "fetch URL branch" act as "fetch URL
           branch:branch".

	2. The "-b build" thing in git-checkout. Worse than just
           looking awkward, this causes a real problem, since my
           git-fetch instructions only work the first time, (if they
           follow them later they're going to run into "branch build
           already exists"). Detached head in 1.5 should help here,
           but see below.

	3. The separation between how to clone and how to fetch into
           an existing repository is annoying. What I'd really like to
           do is just publish something like:

		git://git.project.org/~cworth/project proposed-fix

	   and allow users to just cut-and-paste that to commands as
	   needed. That is, I think it would be nice if "git fetch" or
	   "git clone" could accept the "URL branch" string above and
	   just do the right thing with it.

I've been hoping that some of the recent 1.5 work on git would make
this process simpler. But in fact it makes things worse. First, my
historic instructions don't work anymore with separate remotes. So I
would have to add something like:

	However, if you're using a very recent version of git, (1.5 or
	newer), then you'll need to use this alternate checkout
	command instead:

		git checkout -b build origin/proposed-fix

I really like most of what separate-remotes does. But I don't like
that branch names no longer resolve the same way they used to. Could
we fix git to resolve "branch" as "remotes/*/branch" if unique? That
would allow the old instructions and old habits to continue to work,
(making the change to separate-remotes much more compatible).

Also, if I'm willing to assume (or insist) that users have git 1.5 or
newer, it'd be nice to be able to drop the "-b build" thing thanks to
the new detached HEAD support. But if I suggest doing just:

		git checkout origin/proposed-fix

the user is presented with the following message which is much more
scary than useful in this situation:

	warning: you are not on ANY branch anymore.
	If you meant to create a new branch from the commit, you need -b to
	associate a new branch with the wanted checkout.  Example:
	  git checkout -b <new_branch_name> origin/proposed-fix

The user is getting warned, getting told they perhaps wanted to do
something else, and getting told that if so they would need to use a
different command. But the command I gave does exactly what they
wanted, and following git's advice here would be a bad idea.

I propose this warning be removed here. Otherwise, I either add text
to my instructions telling the user to ignore the warning message they
get, or else I go back to "-b build" and back to all the old problems
it causes.

Thanks for your time and attention,

-Carl

-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Received on Wed Jan 31 07:14:23 2007

This archive was generated by hypermail 2.1.8 : 2007-01-31 07:16:06 EST