Difficulties in advertising a new branch to git newbies

Difficulties in advertising a new branch to git newbies

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 4616 bytes --]

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

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Difficulties in advertising a new branch to git newbies

[Jakub Narebski]

Carl Worth wrote:

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

If youd don't mind fetching more, you can ask just to do "git fetch".
 
But, currently:

  * A parameter <ref> without a colon is equivalent to
    <ref>: when pulling/fetching, so it merges <ref> into the current
    branch without storing the remote branch anywhere locally

I don't think it would be bad if we changed <ref> to mean <ref>:<ref>
and require <ref>: to pull without storing remote branch anywhere locally;
the problem is that we probably want <ref>:<remote>/<ref>.

An alternative would be to tag a fix, and as to do the following

  $ git fetch origin tag proposed-fix

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

An alternative would be to have some branch used only to bring
working directory to given state, by using "git reset --hard <ref>"
while being on it.

E.g.

  $ git checkout build
  $ git reset --hard proposed-fix

(assuming that 'build' branch was created earlier).

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

I rather leave warning, but (perhaps around 1.5.1) remove the
instructions. RTFM (err... I'm not sure we have one about detached HEAD).

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Difficulties in advertising a new branch to git newbies

[Yann Dirson]

On Tue, Jan 30, 2007 at 10:02:40PM +0100, Jakub Narebski wrote:
> > 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.
> 
> I rather leave warning, but (perhaps around 1.5.1) remove the
> instructions. RTFM (err... I'm not sure we have one about detached HEAD).

Or provide a "-q" flag to silence the warning ?

-- 
Yann.

Re: Difficulties in advertising a new branch to git newbies

[Jakub Narebski]

 Yann Dirson wrote:
> On Tue, Jan 30, 2007 at 10:02:40PM +0100, Jakub Narebski wrote:

>>> 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.
>> 
>> I rather leave warning, but (perhaps around 1.5.1) remove the
>> instructions. RTFM (err... I'm not sure we have one about detached HEAD).
> 
> Or provide a "-q" flag to silence the warning ?

Well, it would be nice to have either when command is usually silent to
have "-q" option to it, or have "-q" option to git wrapper (especially
for gitweb).

-- 
Jakub Narebski
Poland

Re: Difficulties in advertising a new branch to git newbies

[Junio C Hamano]

Yann Dirson <ydirson@altern.org> writes:

> On Tue, Jan 30, 2007 at 10:02:40PM +0100, Jakub Narebski wrote:
>> > 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.
>> 
>> I rather leave warning, but (perhaps around 1.5.1) remove the
>> instructions. RTFM (err... I'm not sure we have one about detached HEAD).
>
> Or provide a "-q" flag to silence the warning ?

Or maybe make "-f" to mean "I know what I am doing, do not
warn".

P.S. Jakub, *please* do not break the thread.

Re: Difficulties in advertising a new branch to git newbies

[Jakub Narebski]

Junio C Hamano wrote:
> Yann Dirson <ydirson@altern.org> writes:
> 
>> On Tue, Jan 30, 2007 at 10:02:40PM +0100, Jakub Narebski wrote:
>>>> 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.
>>> 
>>> I rather leave warning, but (perhaps around 1.5.1) remove the
>>> instructions. RTFM (err... I'm not sure we have one about detached HEAD).
>>
>> Or provide a "-q" flag to silence the warning ?
> 
> Or maybe make "-f" to mean "I know what I am doing, do not
> warn".

Unfortunately "-f" in git-checkout mean "force a re-read of everything."
Besides I'd like to have "-q" option for example for git-cat-file for
gitweb...

> P.S. Jakub, *please* do not break the thread.

I'll try.
-- 
Jakub Narebski
Poland

Re: Difficulties in advertising a new branch to git newbies

[Matthias Lederhofer]

How about this:

Create a directory, change into it and run git-init-db.
Get the latest version:
$ git fetch --force URL branch:origin
$ git reset --hard origin
Warning: this will overwrite changes you made to files in the
repository (e.g. the Makefile).

You can also drop the --force if you're sure your branch will always
fast-forward.

Re: Difficulties in advertising a new branch to git newbies

[Matthias Lederhofer]

Matthias Lederhofer <matled@gmx.net> wrote:
> How about this:
> 
> [..]
Reading your original post again: this is not exactly nice but it
should work with any version of git, there shouldn't be many error
conditions and it allows to use the same commands for the initial
checkout and later updates.

Re: Difficulties in advertising a new branch to git newbies

[Jeff King]

On Tue, Jan 30, 2007 at 12:13:26PM -0800, Carl Worth wrote:

> 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

I don't see any reason why we can't scare the user when making a commit,
instead of just checkout out to look around. Something like the patch
below. It needs a few things:
  - remove the old checkout message
  - we wrap the colorization over the multi-line message. Probably a
    color_printf_lines() function should be added
  - if colorization is enabled, print it using color.status.warning
    (default to red).

I'm happy to make all those happen if there is interest (Junio, please
comment).

diff --git a/wt-status.c b/wt-status.c
index 5567868..285c824 100644
--- a/wt-status.c
+++ b/wt-status.c
@@ -22,6 +22,12 @@ static const char use_add_rm_msg[] =
 "use \"git add/rm <file>...\" to update what will be committed";
 static const char use_add_to_include_msg[] =
 "use \"git add <file>...\" to include in what will be committed";
+static const char detach_warn[] =
+"# Any commits you make may become inaccessible if you checkout\n"
+"# another branch. To save them, you may create a new branch\n"
+"# from the current HEAD using:\n"
+"#   git checkout -b <new_branch_name>\n"
+"#";
 
 static int parse_status_slot(const char *var, int offset)
 {
@@ -303,16 +309,13 @@ void wt_status_print(struct wt_status *s)
 	s->is_initial = get_sha1(s->reference, sha1) ? 1 : 0;
 
 	if (s->branch) {
-		const char *on_what = "On branch ";
-		const char *branch_name = s->branch;
-		if (!strncmp(branch_name, "refs/heads/", 11))
-			branch_name += 11;
-		else if (!strcmp(branch_name, "HEAD")) {
-			branch_name = "";
-			on_what = "Not currently on any branch.";
+		const char *c = color(WT_STATUS_HEADER);
+		if (!strncmp(s->branch, "refs/heads/", 11))
+			color_printf_ln(c, "# On branch %s", s->branch+11);
+		else {
+			color_printf_ln(c, "# Not currently on any branch.");
+			color_printf_ln(c, detach_warn);
 		}
-		color_printf_ln(color(WT_STATUS_HEADER),
-			"# %s%s", on_what, branch_name);
 	}
 
 	if (s->is_initial) {

Re: Difficulties in advertising a new branch to git newbies

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Tue, Jan 30, 2007 at 12:13:26PM -0800, Carl Worth wrote:
>
>> 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
>
> I don't see any reason why we can't scare the user when making a commit,
> instead of just checkout out to look around. Something like the patch
> below. It needs a few things:
>   - remove the old checkout message
>   - we wrap the colorization over the multi-line message. Probably a
>     color_printf_lines() function should be added
>   - if colorization is enabled, print it using color.status.warning
>     (default to red).
>
> I'm happy to make all those happen if there is interest (Junio, please
> comment).

That does not protect anything other than interactive "git
commit".  People often do "git commit -m" or "git commit -C".
In addition, rebasing a detached HEAD, merging into a detached
HEAD, cherry-picking onto a detached HEAD or running reset on a
detached HEAD to move to a particular state you want to look at
are all useful and valid operations, and you wouldn't get any
warning when you do so.

I do not think warning at every step that you are "in a funny
state" does not help productivity, so I'd prefer warning upfront
once and be silent afterwards, until you try to come back with
"git checkout <existing branch>", potentially losing your state,
which is what we currently do.

Having said that, I think making "git checkout -f" not to issue
the warning might be enough.  Actually, I would even say it
would make perfect sense.

For situations like Carl's intstruction where a user, who is
purely a sightseer, uses the detached HEAD to go-and-look a
particular state, the fact that "-f" loses the previous local
modifications is not an issue at all.  On the other hand, if the
user is a developer who uses git, the warning upfront (if we
want to keep it for educational purposes, to make people aware
of what is happening) is useful without "-f", and when a user
who is using git to manage his own development, he hopefully
knows what "git checkout -f" means to his local modifications
already.

Re: Difficulties in advertising a new branch to git newbies

[Nicolas Pitre]

On Tue, 30 Jan 2007, Junio C Hamano wrote:

> Having said that, I think making "git checkout -f" not to issue
> the warning might be enough.  Actually, I would even say it
> would make perfect sense.

I agree entirely.


Nicolas

Re: Difficulties in advertising a new branch to git newbies

[Jeff King]

On Tue, Jan 30, 2007 at 05:34:07PM -0800, Junio C Hamano wrote:

> That does not protect anything other than interactive "git
> commit".  People often do "git commit -m" or "git commit -C".

Yes, those should be covered by a message.

> In addition, rebasing a detached HEAD, merging into a detached
> HEAD, cherry-picking onto a detached HEAD or running reset on a

I'm not even sure what it means to rebase a detached HEAD. Merging
and cherry picking should make a similar warning.

> detached HEAD to move to a particular state you want to look at

Running reset on a detached HEAD isn't a problem unless you've done one
of the other things.

> I do not think warning at every step that you are "in a funny
> state" does not help productivity, so I'd prefer warning upfront
> once and be silent afterwards, until you try to come back with
> "git checkout <existing branch>", potentially losing your state,
> which is what we currently do.

I didn't quite parse your first sentence, but I think I get the general
meaning. I just think it is awkward to have to either see such a warning
(or use -f) just to _look_ at detached commits, when you aren't doing
anything even remotely dangerous. The dangerous thing is _creating_
commits on top of a detached head.  I honestly don't think it should be
allowed at all, but since some people have argued that it is useful,
that seems like the place to put warnings. Anything else is just making
things more confusing for the sorts of people Carl is dealing with --
those who merely want to look around.

> For situations like Carl's intstruction where a user, who is
> purely a sightseer, uses the detached HEAD to go-and-look a
> particular state, the fact that "-f" loses the previous local

Yes, though it would be nicer not to have to explain to them why '-f' is
needed.

-Peff

Re: Difficulties in advertising a new branch to git newbies

[Nicolas Pitre]

On Tue, 30 Jan 2007, Jeff King wrote:

> I just think it is awkward to have to either see such a warning
> (or use -f) just to _look_ at detached commits, when you aren't doing
> anything even remotely dangerous. The dangerous thing is _creating_
> commits on top of a detached head.  I honestly don't think it should be
> allowed at all, but since some people have argued that it is useful,
> that seems like the place to put warnings. Anything else is just making
> things more confusing for the sorts of people Carl is dealing with --
> those who merely want to look around.

I disagree again.  Making commits on a detached head is not dangerous.

What is dangerous is moving away from the tip of that detached head 
without attaching it somewhere.  And that case is well covered already.

Also the warning when moving to a detached head is useful to make the 
user aware of what just happened because there is really something 
special about such checkout.  It is not meant to frighten users and if 
it does so then maybe it should be reworked some more.  But IMHO it is 
important that the user be aware of this special state.

But making a warning at commit time is wrong. It is completely 
disconnected from the actual issue and I think it'd create more 
confusion because there is in fact nothing to worry about at the moment 
the commit is made.  The very fact that you think yourself that a 
warning should be displayed at commit time indicates to me that you 
might be a bit confused yourself and such warning if present at commit 
time wouldn't help clearing that confusion at all.

> > For situations like Carl's intstruction where a user, who is
> > purely a sightseer, uses the detached HEAD to go-and-look a
> > particular state, the fact that "-f" loses the previous local
> 
> Yes, though it would be nicer not to have to explain to them why '-f' is
> needed.

In Carl's case suggesting -f is probably not a good idea.  Using -f _is_ 
dangerous and we better not get people into the habit of using -f 
without thinking.

Let's focus on the real issue: the warning message when head gets 
detached.  This message is not meant to frighten users.  It is meant to 
make the user aware of a special state (pretty useful but special 
nevertheless) and give a suggestion about what to do if that state was 
entered by mistake.  So if that message scares users away then it is the 
message itself which is buggy not its presence.


Nicolas

Re: Difficulties in advertising a new branch to git newbies

[Jeff King]

On Wed, Jan 31, 2007 at 09:59:08AM -0500, Nicolas Pitre wrote:

> I disagree again.  Making commits on a detached head is not dangerous.
> 
> What is dangerous is moving away from the tip of that detached head 
> without attaching it somewhere.  And that case is well covered already.

Sure, the dangerous thing is moving away. But my point is there are many
steps leading up to that, and we can warn at any one. However, the
warning is _most_ useful as close to the dangerous thing as possible
(ideally, we would warn when doing the actual dangerous thing, but IIRC,
there was some complexity with that).

IOW, here's a rough flow chart of states and user actions:
         checkout non-branch          commit, etc
(1) regular  ---------> (2) detached,  --------> (3) detached,
         ^                  no commits                commits
         |  checkout branch |  checkout old branch     /\
          \-----------------<--------------------------  |
                                                         |  checkout
                                                         | new branch
                                                         v
                                                   (4) new regular branch

Hopefully my ASCII art skillz are coherent enough. The actual
"dangerous" thing here is moving from 3 to 1. We can theoretically warn
at any transition. Right now we warn moving from 1 to 2. But a large
number of users are just going to go right back to 1, never even doing
anything dangerous! For them, the warning is confusing. I'm proposing
warning between 2 and 3. I would also be happy with warning (and
probably blocking without -f) moving from 3 to 1, which is the actual
dangerous thing. However, I think putting a warning between 2 and 3 is
reasonable, because the next step the user will make from 3 is either
moving to 1 (dangerous) or to 4 (ok), and they must use the correct
git-checkout invocation. So basically, it's our last chance (besides the
actual git-checkout itself) to warn them.

> Also the warning when moving to a detached head is useful to make the 
> user aware of what just happened because there is really something 
> special about such checkout.  It is not meant to frighten users and if 
> it does so then maybe it should be reworked some more.  But IMHO it is 
> important that the user be aware of this special state.

What is so special about it? My argument is that it is not really very
special _until you make commits_. Are there other operations which we
should be warning people about if they have a detached head?

> But making a warning at commit time is wrong. It is completely 
> disconnected from the actual issue and I think it'd create more 
> confusion because there is in fact nothing to worry about at the moment 
> the commit is made.  The very fact that you think yourself that a 
> warning should be displayed at commit time indicates to me that you 
> might be a bit confused yourself and such warning if present at commit 
> time wouldn't help clearing that confusion at all.

I think you are proving my point here. If you think warning at commit
time is too early, then how is warning _before_ that (when we detach)
not too early?

> In Carl's case suggesting -f is probably not a good idea.  Using -f _is_ 
> dangerous and we better not get people into the habit of using -f 
> without thinking.

Agreed.

> Let's focus on the real issue: the warning message when head gets 
> detached.  This message is not meant to frighten users.  It is meant to 
> make the user aware of a special state (pretty useful but special 
> nevertheless) and give a suggestion about what to do if that state was 
> entered by mistake.  So if that message scares users away then it is the 
> message itself which is buggy not its presence.

Again, I don't understand why the state is special (aside from the
possibility of losing commits).

-Peff

Re: Difficulties in advertising a new branch to git newbies

[Nicolas Pitre]

On Wed, 31 Jan 2007, Jeff King wrote:

> On Wed, Jan 31, 2007 at 09:59:08AM -0500, Nicolas Pitre wrote:
> 
> > I disagree again.  Making commits on a detached head is not dangerous.
> > 
> > What is dangerous is moving away from the tip of that detached head 
> > without attaching it somewhere.  And that case is well covered already.
> 
> Sure, the dangerous thing is moving away. But my point is there are many
> steps leading up to that, and we can warn at any one. However, the
> warning is _most_ useful as close to the dangerous thing as possible
> (ideally, we would warn when doing the actual dangerous thing, but IIRC,
> there was some complexity with that).

The _only_ dangerous thing is moving away.  Warning at any step is far 
more annoying than warning (actually only notifying) only once when the 
detached head state is entered.

> IOW, here's a rough flow chart of states and user actions:
>          checkout non-branch          commit, etc
> (1) regular  ---------> (2) detached,  --------> (3) detached,
>          ^                  no commits                commits
>          |  checkout branch |  checkout old branch     /\
>           \-----------------<--------------------------  |
>                                                          |  checkout
>                                                          | new branch
>                                                          v
>                                                    (4) new regular branch
> 
> Hopefully my ASCII art skillz are coherent enough. The actual
> "dangerous" thing here is moving from 3 to 1. We can theoretically warn
> at any transition. Right now we warn moving from 1 to 2. But a large
> number of users are just going to go right back to 1, never even doing
> anything dangerous! For them, the warning is confusing.

Let's fix the warning then.  But it must stay just because it is 
important that the user know _why_ and _when_ the head became detached.  
Realizing that head is detached later is far more confusing if the user 
just don't know how that happened.

> I'm proposing warning between 2 and 3.

Given that the commit template already says that the head is detached is 
IMHO far enough given the actual "dangerousness" of the operation.

> I would also be happy with warning (and
> probably blocking without -f) moving from 3 to 1, which is the actual
> dangerous thing.

And that is already what is happening.

> However, I think putting a warning between 2 and 3 is
> reasonable, because the next step the user will make from 3 is either
> moving to 1 (dangerous) or to 4 (ok), and they must use the correct
> git-checkout invocation. So basically, it's our last chance (besides the
> actual git-checkout itself) to warn them.

No it is not.  The user cannot escape the detached head state (moving 
from 3 to 1) without -f or creating a new branch already.  Additional 
warning between (2) and (3) does nothing but add annoyance to the user 
experience.

> > Also the warning when moving to a detached head is useful to make the 
> > user aware of what just happened because there is really something 
> > special about such checkout.  It is not meant to frighten users and if 
> > it does so then maybe it should be reworked some more.  But IMHO it is 
> > important that the user be aware of this special state.
> 
> What is so special about it? My argument is that it is not really very
> special _until you make commits_. Are there other operations which we
> should be warning people about if they have a detached head?

It is a different state and the user must know why.  When doing a commit 
it is too late to say "oh btw your head was detached a while ago".

> > But making a warning at commit time is wrong. It is completely 
> > disconnected from the actual issue and I think it'd create more 
> > confusion because there is in fact nothing to worry about at the moment 
> > the commit is made.  The very fact that you think yourself that a 
> > warning should be displayed at commit time indicates to me that you 
> > might be a bit confused yourself and such warning if present at commit 
> > time wouldn't help clearing that confusion at all.
> 
> I think you are proving my point here. If you think warning at commit
> time is too early, then how is warning _before_ that (when we detach)
> not too early?

Did I say anything about it being too early?

I say that it is unnecessary and redundent, and that it would create 
more confusion than it clears.

> > In Carl's case suggesting -f is probably not a good idea.  Using -f _is_ 
> > dangerous and we better not get people into the habit of using -f 
> > without thinking.
> 
> Agreed.
> 
> > Let's focus on the real issue: the warning message when head gets 
> > detached.  This message is not meant to frighten users.  It is meant to 
> > make the user aware of a special state (pretty useful but special 
> > nevertheless) and give a suggestion about what to do if that state was 
> > entered by mistake.  So if that message scares users away then it is the 
> > message itself which is buggy not its presence.
> 
> Again, I don't understand why the state is special (aside from the
> possibility of losing commits).

It is special because it has an entry point and an exit point, unlike 
being on any branch where there is no such notion.  So it is important 
to know when/how you enters it and how you may leave it.  Intermediate 
operations don't have to be special with useless warnings.


Nicolas

Re: Difficulties in advertising a new branch to git newbies

[Jeff King]

On Wed, Jan 31, 2007 at 01:59:37PM -0500, Nicolas Pitre wrote:

> > I would also be happy with warning (and
> > probably blocking without -f) moving from 3 to 1, which is the actual
> > dangerous thing.
> And that is already what is happening.

Doh! I'm a complete moron. Sorry, but I thought we were _not_ warning
there in favor of the warning at time of detachment. I even did a test,
but I botched it.

So please, accept my apology and assume I have hit myself over the head
with the clue stick several times. Warning at commit time _is_ stupid,
since we can complain at the correct time.

> Let's fix the warning then.  But it must stay just because it is 
> important that the user know _why_ and _when_ the head became detached.  
> Realizing that head is detached later is far more confusing if the user 
> just don't know how that happened.

OK, I completely see your point now; it doesn't have to be a _warning_
per se, but rather to let the user know this is when the state changed
(so that later if they do get a warning, it makes more sense).

> > > But making a warning at commit time is wrong. It is completely 
> > > disconnected from the actual issue and I think it'd create more 
> > > confusion because there is in fact nothing to worry about at the moment 
> > > the commit is made.  The very fact that you think yourself that a 
> > > warning should be displayed at commit time indicates to me that you 
> > > might be a bit confused yourself and such warning if present at commit 
> > > time wouldn't help clearing that confusion at all.
> > 
> > I think you are proving my point here. If you think warning at commit
> > time is too early, then how is warning _before_ that (when we detach)
> > not too early?
> 
> Did I say anything about it being too early?
> 
> I say that it is unnecessary and redundent, and that it would create 
> more confusion than it clears.

You said "...there is in fact nothing to worry about at the moment the
commit is made." My point is that there is in fact nothing to worry
about at the moment that you detach, thus why should one get a warning
and not the other. But I agree that if you want the later warning to
make sense, it might be helpful to note that point (and I think it's
getting too fancy to tuck away that information and have the actual
warning say "When you moved your HEAD to foo~32, you were no longer on a
branch, therefore...")

So IOW, I think I agree with you now. :)

Again, sorry for the (my) confusion.

-Peff

Re: Difficulties in advertising a new branch to git newbies

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Wed, Jan 31, 2007 at 09:59:08AM -0500, Nicolas Pitre wrote:
>
>> Also the warning when moving to a detached head is useful to make the 
>> user aware of what just happened because there is really something 
>> special about such checkout.  It is not meant to frighten users and if 
>> it does so then maybe it should be reworked some more.  But IMHO it is 
>> important that the user be aware of this special state.
>
> What is so special about it? My argument is that it is not really very
> special _until you make commits_. Are there other operations which we
> should be warning people about if they have a detached head?

I think you (and others in the thread) are forgetting that
moving to a particular state by resetting can create a state
that you may want to keep a pointer to, but you do not have any
existing ref.  That's one of the reasons why we do not merely
check if the detached HEAD is not reachable from any of the
existing refs when coming back.  Instead, we check and warn if
the detached HEAD does not exactly match one of the existing
refs.

Imagine "git bisect" did not exist, or was not powerful enough,
and the user was doing it by hand using something other than
"git bisect" to guide him which state to go next, or the user
did not want to use the special "bisect" branch, or some
combination of the above.  You move your detached HEAD around
and finally you are at the commit you are interested in.  You
haven't marked it in some way (perhaps "git tag") yet.  You
haven't made any commit, and the commit is reachable in some
way, but all the work to reach that state will be lost unless
you jot its commit object name down somewhere.

So "until you make commits" is not sufficient, which means that
covering all the way you can make commits isn't, either.

Re: Difficulties in advertising a new branch to git newbies

[Theodore Tso]

On Wed, Jan 31, 2007 at 12:20:33PM -0800, Junio C Hamano wrote:
> I think you (and others in the thread) are forgetting that
> moving to a particular state by resetting can create a state
> that you may want to keep a pointer to, but you do not have any
> existing ref.  That's one of the reasons why we do not merely
> check if the detached HEAD is not reachable from any of the
> existing refs when coming back.  Instead, we check and warn if
> the detached HEAD does not exactly match one of the existing
> refs.

Is that an important distinction?  The way the user got there was by
manually specifying the SHA-1 shash of the commit to git-checkout.  So
if the user could get there once, the user could get there again a
second time.  Just because we don't have a name to that precise commit
inside the git system doesn't necessary mean the user can't get back
there.   In fact, the user probably could via "history | grep 'git checkout'".

> So "until you make commits" is not sufficient, which means that
> covering all the way you can make commits isn't, either.

My personal belief is that covering all the way you can make commits
is where you want to be putting the check.  If I say something like

git checkout f00b51b8

There's nothing dangerous about that statement.  To argue that this is
dangerous and the git needs to warn me because I might not be able to
get back to it seems silly.  Of _course_ I can get back there; the
same way I got here in the first place --- By simply saying, "git
checkout f00b51b8" again!

And if I tell a user that they should try out a particular version of
the code, issueing a scary message right then there is pointless if
they are only going to be doing a read-only browse of the tree, is
just a Bad Thing.  The best place to warn them really is when they
modify the tree.

Otherwise, we'll be educating users to use the -f flag, or telling
users to "ignore the warning, git's being silly", neither of which is
desirable.

						- Ted

Re: Difficulties in advertising a new branch to git newbies

[Junio C Hamano]

Theodore Tso <tytso@mit.edu> writes:

> ...  Just because we don't have a name to that precise commit
> inside the git system doesn't necessary mean the user can't get back
> there.
> In fact, the user probably could via "history | grep 'git checkout'".

If you mean grep 'git checkout|git reset' perhaps.  After
checking out a specific commit (because the user was told about
the commit out-of-band, say, via e-mail), the user can still
visit other commits with e.g. "git reset --hard HEAD~20".

>> So "until you make commits" is not sufficient, which means that
>> covering all the way you can make commits isn't, either.
>
> My personal belief is that covering all the way you can make commits
> is where you want to be putting the check.  If I say something like
>
> git checkout f00b51b8
>
> There's nothing dangerous about that statement.

I do not think anybody is arguing that particular checkout is
dangerous.  The warning message is about the fact that your HEAD
is now detached, which might not have been what you intended
(and you will later get a real warning when you do a really
dangerous thing, which is "to come back and lose your point").

Re: Difficulties in advertising a new branch to git newbies

[Jakub Narebski]

Theodore Tso wrote:
> On Wed, Jan 31, 2007 at 12:20:33PM -0800, Junio C Hamano wrote:

>> I think you (and others in the thread) are forgetting that
>> moving to a particular state by resetting can create a state
>> that you may want to keep a pointer to, but you do not have any
>> existing ref.  That's one of the reasons why we do not merely
>> check if the detached HEAD is not reachable from any of the
>> existing refs when coming back.  Instead, we check and warn if
>> the detached HEAD does not exactly match one of the existing
>> refs.
> 
> Is that an important distinction?  The way the user got there was by
> manually specifying the SHA-1 shash of the commit to git-checkout.  So
> if the user could get there once, the user could get there again a
> second time.  Just because we don't have a name to that precise commit
> inside the git system doesn't necessary mean the user can't get back
> there.   In fact, the user probably could via "history | grep 'git
> checkout'". 

Have you read further? git-bisect could (and probably should) use detached
HEAD instead of special 'bisect' branch. Doing bisection can be hard work
(checking if commit is good or bad might take time) and we don't want to
lose it.

Besides, history has finite length, and you could get to the state not only
via "git checkout", but also via "git reset --hard".

Reflog for detached HEAD would help in this.
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Difficulties in advertising a new branch to git newbies

[Nicolas Pitre]

On Tue, 30 Jan 2007, Jeff King wrote:

> On Tue, Jan 30, 2007 at 12:13:26PM -0800, Carl Worth wrote:
> 
> > 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

Note that the latest revision on the master branch of git has a slightly 
less scary message.

> I don't see any reason why we can't scare the user when making a commit,
> instead of just checkout out to look around. Something like the patch
> below. It needs a few things:
>   - remove the old checkout message

I don't think that is a good idea in general.

It is already kind of a challenge to teach people about git's branch 
concept.  The detached head is yet another exotic thing about git that 
is sure not to be really obvious to everyone.  Now if you remove the 
message to hide the detached head state from the user just to come later 
on with a "hey btw did you know that your head was detached?" message 
then you can be assured that most people will simply go WTF.


Nicolas

Re: Difficulties in advertising a new branch to git newbies

[Daniel Barkalow]

On Tue, 30 Jan 2007, Carl Worth wrote:

> 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

I think the warning should just be something where a user following your 
instructions will say, "ah, yes, that's actually what I want." Maybe:

  warning: you are now browsing the history without a local branch. You 
  will not be able to commit changes unless you create a new local branch 
  with "git checkout -b <new_branch_name>".

It's a bit silly for us to simply warn people that they're using this 
feature, rather than telling them what the potential downside is. Since 
it's marked as a warning, with no further information, the intuitive 
inference is that all sorts of bad things could happen (like, too many for 
us to list). At least we don't say "warning: your HEAD is now detatched" 
but still...

	-Daniel
*This .sig left intentionally blank*

Re: Difficulties in advertising a new branch to git newbies

[Nicolas Pitre]

On Tue, 30 Jan 2007, Daniel Barkalow wrote:

>   warning: you are now browsing the history without a local branch. You 
>   will not be able to commit changes unless you create a new local branch 
>   with "git checkout -b <new_branch_name>".

This isn't true.  You can commit on top of a detached head.  In fact you 
can do almost anything.


Nicolas

Re: Difficulties in advertising a new branch to git newbies

[Daniel Barkalow]

On Tue, 30 Jan 2007, Nicolas Pitre wrote:

> On Tue, 30 Jan 2007, Daniel Barkalow wrote:
> 
> >   warning: you are now browsing the history without a local branch. You 
> >   will not be able to commit changes unless you create a new local branch 
> >   with "git checkout -b <new_branch_name>".
> 
> This isn't true.  You can commit on top of a detached head.  In fact you 
> can do almost anything.

"Commits you make will not be attached to permanent state unless you 
create a local branch"? I'm not sure how the feature turned out to work, 
but I know that (a) you're fine if you don't make any commits and (b) the 
behavior is more like what happens with anonymous checkouts of other 
people's repositories in non-distributed SCMs, so people will tend to
underestimate what they can do with this, rather than overestimating it 
and getting into trouble.

I suppose it's reasonable to warn at commit time, if we ended up going 
with allowing commits like normal.

	-Daniel
*This .sig left intentionally blank*

Re: Difficulties in advertising a new branch to git newbies

[Nicolas Pitre]

On Wed, 31 Jan 2007, Daniel Barkalow wrote:

> On Tue, 30 Jan 2007, Nicolas Pitre wrote:
> 
> > On Tue, 30 Jan 2007, Daniel Barkalow wrote:
> > 
> > >   warning: you are now browsing the history without a local branch. You 
> > >   will not be able to commit changes unless you create a new local branch 
> > >   with "git checkout -b <new_branch_name>".
> > 
> > This isn't true.  You can commit on top of a detached head.  In fact you 
> > can do almost anything.
> 
> "Commits you make will not be attached to permanent state unless you 
> create a local branch"? I'm not sure how the feature turned out to work, 
> but I know that (a) you're fine if you don't make any commits and (b) the 
> behavior is more like what happens with anonymous checkouts of other 
> people's repositories in non-distributed SCMs, so people will tend to
> underestimate what they can do with this, rather than overestimating it 
> and getting into trouble.
> 
> I suppose it's reasonable to warn at commit time, if we ended up going 
> with allowing commits like normal.

I disagree.

It is not the commit which is dangerous when the head is detached.  It 
is the checkout of another branch.  And this case is covered already 
such that the checkout is refused unless you actually create a branch 
for your detached head or you give -f to checkout to override the 
protection.

Giving a warning at commit time is not the place where the user has to 
be aware of the issue since it is indeed not the place where there is 
any issue to worry about.


Nicolas

Re: Difficulties in advertising a new branch to git newbies

[J. Bruce Fields]

On Wed, Jan 31, 2007 at 09:31:00AM -0500, Nicolas Pitre wrote:
> It is not the commit which is dangerous when the head is detached.  It 
> is the checkout of another branch.  And this case is covered already 
> such that the checkout is refused unless you actually create a branch 
> for your detached head or you give -f to checkout to override the 
> protection.
> 
> Giving a warning at commit time is not the place where the user has to 
> be aware of the issue since it is indeed not the place where there is 
> any issue to worry about.

By the same argument, the original checkout of a non-branch is also not
the place for a warning; by the time you commit and then do a checkout
to switch away from the new commit, that original checkout may be a
distant memory.

--b.

Re: Difficulties in advertising a new branch to git newbies

[Jakub Narebski]

J. Bruce Fields wrote:
> On Wed, Jan 31, 2007 at 09:31:00AM -0500, Nicolas Pitre wrote:

>> It is not the commit which is dangerous when the head is detached.  It 
>> is the checkout of another branch.  And this case is covered already 
>> such that the checkout is refused unless you actually create a branch 
>> for your detached head or you give -f to checkout to override the 
>> protection.
>> 
>> Giving a warning at commit time is not the place where the user has to 
>> be aware of the issue since it is indeed not the place where there is 
>> any issue to worry about.

I'd like to have some configuration option to make git more careful
and prohibit commiting in detached HEAD state (the default being that
you can commit on top of detached HEAD). More secure but less powerfull.
 
> By the same argument, the original checkout of a non-branch is also not
> the place for a warning; by the time you commit and then do a checkout
> to switch away from the new commit, that original checkout may be a
> distant memory.

But the initial checkout of a non-branch is place where we can notify
user that he does something unexpected / unusual. Though I think that
single-line warning would be enough...
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Difficulties in advertising a new branch to git newbies

[Nicolas Pitre]

On Wed, 31 Jan 2007, Jakub Narebski wrote:

> I'd like to have some configuration option to make git more careful
> and prohibit commiting in detached HEAD state (the default being that
> you can commit on top of detached HEAD). More secure but less powerfull.

And what is the purpose of such an artificial annoyance that no one will 
turn on on purpose?

You have to _realize_ that there is nothing wrong with such commits.  
Merely having a config option to prohibit them not only is senseless 
technically but it also send the wrong message to users.

> > By the same argument, the original checkout of a non-branch is also not
> > the place for a warning; by the time you commit and then do a checkout
> > to switch away from the new commit, that original checkout may be a
> > distant memory.
> 
> But the initial checkout of a non-branch is place where we can notify
> user that he does something unexpected / unusual. Though I think that
> single-line warning would be enough...

There is a balance problem there.  Too large a message might be annoying 
but a too short one might not convey enough information not to be yet 
more confusing.


Nicolas

Re: Difficulties in advertising a new branch to git newbies

[Daniel Barkalow]

On Wed, 31 Jan 2007, Nicolas Pitre wrote:

> On Wed, 31 Jan 2007, Daniel Barkalow wrote:
> 
> > On Tue, 30 Jan 2007, Nicolas Pitre wrote:
> > 
> > > On Tue, 30 Jan 2007, Daniel Barkalow wrote:
> > > 
> > > >   warning: you are now browsing the history without a local branch. You 
> > > >   will not be able to commit changes unless you create a new local branch 
> > > >   with "git checkout -b <new_branch_name>".
> > > 
> > > This isn't true.  You can commit on top of a detached head.  In fact you 
> > > can do almost anything.
> > 
> > "Commits you make will not be attached to permanent state unless you 
> > create a local branch"? I'm not sure how the feature turned out to work, 
> > but I know that (a) you're fine if you don't make any commits and (b) the 
> > behavior is more like what happens with anonymous checkouts of other 
> > people's repositories in non-distributed SCMs, so people will tend to
> > underestimate what they can do with this, rather than overestimating it 
> > and getting into trouble.
> > 
> > I suppose it's reasonable to warn at commit time, if we ended up going 
> > with allowing commits like normal.
> 
> I disagree.
> 
> It is not the commit which is dangerous when the head is detached.  It 
> is the checkout of another branch.  And this case is covered already 
> such that the checkout is refused unless you actually create a branch 
> for your detached head or you give -f to checkout to override the 
> protection.
> 
> Giving a warning at commit time is not the place where the user has to 
> be aware of the issue since it is indeed not the place where there is 
> any issue to worry about.

At commit time, the user is reasonably likely to be doing something 
unintended (at least, it's more likely that the user is doing something 
unintended by committing with a detatched head than that the user is doing 
something unintended by detatching the head). Certainly the only time 
there's any danger of losing work is when the head is detatched and a 
commit has been made since it was set, because otherwise there's either no 
work to lose, or no commits could be becoming unreachable.

I suspect that there will be people from other SCMs who will assume 
they're back on a local branch if the system lets them commit, because 
they would be prohibited from committing on top of an anonymous checkout 
or a historical commit. Of course, they can cherry-pick the misplaced 
commit, so it's not a big deal, but I think it's where a naive user would 
be getting into a state they don't understand.

	-Daniel
*This .sig left intentionally blank*

Re: Difficulties in advertising a new branch to git newbies

[Nicolas Pitre]

On Wed, 31 Jan 2007, Daniel Barkalow wrote:

> On Wed, 31 Jan 2007, Nicolas Pitre wrote:
> 
> > Giving a warning at commit time is not the place where the user has to 
> > be aware of the issue since it is indeed not the place where there is 
> > any issue to worry about.
> 
> At commit time, the user is reasonably likely to be doing something 
> unintended (at least, it's more likely that the user is doing something 
> unintended by committing with a detatched head than that the user is doing 
> something unintended by detatching the head). Certainly the only time 
> there's any danger of losing work is when the head is detatched and a 
> commit has been made since it was set, because otherwise there's either no 
> work to lose, or no commits could be becoming unreachable.

There is protection against losing a commit made on top of a detached 
head already.  And when reflog of detached head can be completed then 
there won't be any ways to lose them regardless.  Preventing or making 
it difficult or annoying to commit on top of a detached head 1) makes no 
technical sense and 2) doesn't address the real issue.

> I suspect that there will be people from other SCMs who will assume 
> they're back on a local branch if the system lets them commit, because 
> they would be prohibited from committing on top of an anonymous checkout 
> or a historical commit.

I don't follow you here.

Why would you be prevented from performing a commit on top of an 
historical commit?  That is the whole point of a detached head: making 
things to a checkout that usually should remain read-only.  This is why 
you can fetch and merge tracking branches, diff against taged commits or 
tracking branches, etc.  But if you _checkout_ a read-only branch/tag 
then either we checkout every file read-only to inforce that face and 
piss off users, or let them do as much as they wish _including_ commits 
but have a safety gate for the only operation that could otherwise 
actualy lose work.

And since the commit template already mention "Not currently on any 
branch" I think the user is reminded already that she's still not on a 
local branch.

> Of course, they can cherry-pick the misplaced 
> commit, so it's not a big deal, but I think it's where a naive user would 
> be getting into a state they don't understand.

That's why the warning when detaching head is important:

|warning: you are not on ANY branch anymore.
|If you meant to create a new branch from this checkout, you may still do
|so (now or later) by using -b with the checkout command again.  Example:
|  git checkout -b <new_branch_name>

The "now or later" is there exactly to tone down the warning.  And 
actually we could do s/warning/note" to make it even less frightening.  

But I think it is important to tell the user up front about that fact. 
Then, when the user tries to commit and sees "Not currently on any 
branch" then she'll go "oh sure it told me so before" and maybe even 
"that's so cool I can perform commits even in this case!".  But if the 
user sees that "Not currently on any branch" line without having been 
notified at the moment it happened then she'll only think "WTF did I do 
to get here".

But if a user did work, even unexpectedly, on top of a detached head 
then the worst thing you can trow at her face is :"sorry, you cannot 
commit your work here" or "committing on a detached head risk losing 
your work" because those are technically untrue and really unfriendly.

When it is really possible to lose change unexpectedly is when 
performing another checkout.  And currently you simply won't be able to 
do it.  You'll get this instead:

|You are not on any branch and switching to branch 'master'
|may lose your changes.  At this point, you can do one of two things:
| (1) Decide it is Ok and say 'git checkout -f master';
| (2) Start a new branch from the current commit, by saying
|     'git checkout -b <branch-name>'.
|Leaving your HEAD detached; not switching to branch 'master'.

There is no way the user might still be confused here. Any commit time 
warning is useless and redundent when you have this message when it 
really matters.

This is flexibility and safety together and I think this is really 
powerful.


Nicolas

Re: Difficulties in advertising a new branch to git newbies

[Guilhem Bonnefille]

On 1/30/07, Carl Worth <cworth@cworth.org> wrote:
> 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).

If the user is not a developer and only interested in testing, what
about a simple snapshot tarball?
So, you prepare the fix and then you pack everything in a
myapp-timestamp.tar.gz and send this tarball to the user.

-- 
Guilhem BONNEFILLE
-=- #UIN: 15146515 JID: guyou@im.apinc.org MSN: guilhem_bonnefille@hotmail.com
-=- mailto:guilhem.bonnefille@gmail.com
-=- http://nathguil.free.fr/

Re: Difficulties in advertising a new branch to git newbies

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1426 bytes --]

On Wed, 31 Jan 2007 14:13:42 +0100, "Guilhem Bonnefille" wrote:
> If the user is not a developer and only interested in testing, what
> about a simple snapshot tarball?
> So, you prepare the fix and then you pack everything in a
> myapp-timestamp.tar.gz and send this tarball to the user.

That's bad for all the same reasons we don't send tarballs around to
each other.

But here are several concrete points:

1. I want to be able to easily publicize a new branch with
   instructions that anyone can use, (regardless of git experience).

2. I've got the stuff available in a git branch already, and I don't
   want to do any more work.

3. I want the exchange to be as efficient as possible, (I might send
   multiple fixes in series to the user and it'd be really nice to
   take advantage of git's efficiency here).

4. I don't want to condemn the user to never being able to learn
   git. If I make this easy for the user then I get a nice lead-in to
   teach the user new things, (which is good for me since it helps me
   if the user starts sending me git commits rather than random
   patches without commit messages connected to who-knows-what
   tar-file version of the software, etc.)

etc. etc.

-Carl

PS. All that being said, our project does publish periodic tar-file
snapshots. But that's really for a different situation: specifically,
for people with whom I'm not already engaged in any conversation at
all.

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Difficulties in advertising a new branch to git newbies

[Johannes Schindelin]

Hi,

On Wed, 31 Jan 2007, Carl Worth wrote:

> On Wed, 31 Jan 2007 14:13:42 +0100, "Guilhem Bonnefille" wrote:
> > If the user is not a developer and only interested in testing, what
> > about a simple snapshot tarball?
> > So, you prepare the fix and then you pack everything in a
> > myapp-timestamp.tar.gz and send this tarball to the user.
> 
> That's bad for all the same reasons we don't send tarballs around to 
> each other.

Well, that's not completely fair. Guilhem has a point here.

> 1. I want to be able to easily publicize a new branch with
>    instructions that anyone can use, (regardless of git experience).

How about gitweb, with a snapshot link? It's as easy as it gets. Even 
those Windows idio^H^H^H^Husers can unpack tar.gz files by now, and you 
send them just a link. They can even see what was fixed, and when, if they 
care enough.
 
> > 2. I've got the stuff available in a git branch already, and I don't
>    want to do any more work.

That is one of the lousiest excuses in this world. Unfortunately, I hear 
it very, very often. (I mean the second sentence.)

> 3. I want the exchange to be as efficient as possible, (I might send
>    multiple fixes in series to the user and it'd be really nice to
>    take advantage of git's efficiency here).

There's two kinds of efficient here. Efficient in the sense of network 
traffic, or in the sense of time spent talking back and forth, until the 
package is finally tested.

If the efficiency you are thriving for is network traffic, go a head, make 
the user use git.

However, if it is the other efficiency you want to achieve, stay away from 
git. Chances are that your user will never appreciate what git can to for 
her, and just wants to test the darned package, and be done with it, 
thank you very much.

> 4. I don't want to condemn the user to never being able to learn
>    git. If I make this easy for the user then I get a nice lead-in to
>    teach the user new things, (which is good for me since it helps me
>    if the user starts sending me git commits rather than random
>    patches without commit messages connected to who-knows-what
>    tar-file version of the software, etc.)

That's nice of you. But it might just be that you royally p*ss the 
customer off, because he does not have time for that game.

Ciao,
Dscho

Re: Difficulties in advertising a new branch to git newbies

[Santi Béjar]

On 1/30/07, Carl Worth <cworth@cworth.org> wrote:
> 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.

Actually it is the same "problem" as when you want to work on the
non-HEAD remote branch.

Currently I do (with current git):

git clone git://...
git checkout -b ${branch} origin/${branch}
git config branch.${branch}.merge refs/heads/${branch}

then they could update this with just:

git pull

It would be nice if:

git clone -b ${branch} git://...

would be equivalent of the above three commands.

Santi

Re: Difficulties in advertising a new branch to git newbies

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 982 bytes --]

On Wed, 31 Jan 2007 20:27:52 +0100, "=?ISO-8859-1?Q?Santi_B=E9jar?=" wrote:
> Actually it is the same "problem" as when you want to work on the
> non-HEAD remote branch.

Yes, exactly.

> It would be nice if:
>
> git clone -b ${branch} git://...
>
> would be equivalent of the above three commands.

Yes, something like that would be extremely helpful!

In addition, it would be great to have a command that did the same
setup within an existing repository.

And I would be most happy if the two commands for these two use cases
shared as much syntax as possible, so I could publish one string and
users could cut-and-paste it to either command as appropriate.

One string I would have liked would have been "git://... ${branch}",
but existing git-clone and git-fetch command syntax is not too
amenable for that, (git-clone interprets an argument after the URL as
the name of the local directory to create while git-fetch interprets
the argument after the URL as a refspec).

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Difficulties in advertising a new branch to git newbies

[Josef Weidendorfer]

On Wednesday 31 January 2007, Carl Worth wrote:
> > It would be nice if:
> >
> > git clone -b ${branch} git://...

Nice indeed.

Additionally, it would be nice for clone to directly
checkout tags. Why not an option "--checkout <ref>"
to directly checkout <ref> after cloning?

This goes nicely with the "-b" option
to create a new branch. A "-b <branch>" option alone would
imply "--checkout origin/<branch>". And without "--checkout"
or "-b" option it defaults to "-b master" which gives
exactly the same behavior as now.

This way,

 git clone --checkout v1.0 git://...

would checkout tag v1.0, and use a detached head for it.

> In addition, it would be great to have a command that did the same
> setup within an existing repository.

Why not use "git clone" for this?
Currently, the man page says about the directory it will clone into:

 "Cloning into an existing directory is not allowed."

But we could relax this: if the specified directory is the root of
a checkout (ie. with a .git subdir), we would clone a remote repository
into the same local repository. However, this should not default
to "-b master", ie. not switch the current branch. Additionally, the
remote name should not default to "origin", but to the 
"humanish" part of the source repository. IMHO we should have done
the latter since long time ago, as a remote "origin" is not really
useful once you work with branches from multiple remote repositories.

Doing this,

 git clone git://... <newdir>

would be the equivalent of

 mkdir <newdir>
 cd <newdir>
 git init
 git clone -b master git://... .

which IMHO would make a lot of sense.
 
> And I would be most happy if the two commands for these two use cases
> shared as much syntax as possible, so I could publish one string and
> users could cut-and-paste it to either command as appropriate.

You would say:

"To get version <xyz>, do a

  git clone --checkout <xyz> git://...

If you already have a local clone of the repository, append the
directory of your local repository as target to clone this version
into".


> One string I would have liked would have been "git://... ${branch}"

IMHO "-b" option is better as it tells you that it creates a new
local development branch for you.

Josef

> but existing git-clone and git-fetch command syntax is not too
> amenable for that, (git-clone interprets an argument after the URL as
> the name of the local directory to create while git-fetch interprets
> the argument after the URL as a refspec).
> 
> -Carl
> 

Re: Difficulties in advertising a new branch to git newbies

[Santi Béjar]

On 2/1/07, Josef Weidendorfer <Josef.Weidendorfer@gmx.de> wrote:
> On Wednesday 31 January 2007, Carl Worth wrote:
> > > It would be nice if:
> > >
> > > git clone -b ${branch} git://...
>
> Nice indeed.
>
> Additionally, it would be nice for clone to directly
> checkout tags. Why not an option "--checkout <ref>"
> to directly checkout <ref> after cloning?

Maybe, I'm not sure.

> > In addition, it would be great to have a command that did the same
> > setup within an existing repository.
>
> Why not use "git clone" for this?
> Currently, the man page says about the directory it will clone into:
>
>  "Cloning into an existing directory is not allowed."
>
> But we could relax this: if the specified directory is the root of
> a checkout (ie. with a .git subdir), we would clone a remote repository
> into the same local repository.

You can do it with git-remote. I think it is sensible to have a
command to get a new repository and a command to have a new remote.

For the "work on the non-HEAD branch" I think we could have:

# clone a remote repository and start working with branch ${branch}
$ git clone -b ${branch} ${url}

# add a new branch based on a remote branch,
# and configure to pull from there.
$ git branch ${branch} ${remote_branch}
$ git checkout -b ${branch} ${remote_branch}

as you see it is the current syntax, so I suggest to automatically
setup the branch.${branch}.{remote,merge} configs to follow the
${remote_branch} if this is sensible. So for example

$ git clone ${url_of_git.git}
$ cd git
$ git checkout -b maint origin/maint
$ git-config -l | grep ^branch.maint
branch.master.remote=origin
branch.master.merge=refs/heads/maint

( or branch.master.merge=refs/remotes/origin/maint )

This changes the current behaviour, but I think it make sense. If this
is not possible another way would be to have another option (-r for
remote, or -f for follow, or -p for pull, or -m for merge, ...) as:

$ git branch ${branch} -r ${remote_branch}
$ git checkout -b ${branch} -r ${remote_branch}

And if you want to add/change the remote/merge config for an existing
branch, in addition to doing this with git-config, git-remote could do
it as it currently shows the tracking branches.

Santi

Re: Difficulties in advertising a new branch to git newbies

[Jakub Narebski]

Carl Worth wrote:
[cut]

By the way, you can get new layout with old git using --use-separate-remote
option to git clone (which is present I think from around Jun 2006).
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Difficulties in advertising a new branch to git newbies

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 1823 bytes --]

On Tue, 30 Jan 2007 12:13:26 -0800, Carl Worth wrote:
> 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.

When I first brought up this thread we had lots of good discussion
about detached head that led to improved (or eliminated) warning
messages, and some good motivation for HEAD reflog.

Meanwhile, there's still a piece of the original problem that was not
addressed:

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

Is there any feedback on the above? I just ran into this problem again
tonight, giving out instructions of "git checkout -b build
proposed-fix" and then bracing myself to have the user complain about
an error of:

	git checkout: updating paths is incompatible with switching branches/forcing
	Did you intend to checkout 'proposed-fix' which can not be resolved as commit?

To which I'd have to respond, "Oh, you're using a newer git. In your
case use 'git checkout -b build origin/proposed-fix'".

So, could we fix this so that a remote branch name will resolve
without the "origin/" prefix if it is not ambiguous?

I can imagine the resolution rules are already fairly complicated, (I
don't even know what they all are already). But when there is no
ambiguity, and when the behavior would be backwards compatible to git
before separate-remotes, is there any reason this would be a bad idea?

Thanks,

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Difficulties in advertising a new branch to git newbies

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> So, could we fix this so that a remote branch name will resolve
> without the "origin/" prefix if it is not ambiguous?

I am fairly negative on this one, especially I do not think the
symptom deserves to be described with the word "fix".  DWIM is
good, but it has bounds, and this particular one feels it is
slightly on the other side of the boundary.  We currently only
DWIM out of a fixed set of patterns -- if you want to extend it,
it would now require readdir() to expand.

> I can imagine the resolution rules are already fairly complicated, (I
> don't even know what they all are already).

If you add another DWIM rule, then I suspect that you would have
harder time explaining why they get "hey, that is ambiguous"
error.

Re: Difficulties in advertising a new branch to git newbies

[Junio C Hamano]

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

> If you add another DWIM rule, then I suspect that you would have
> harder time explaining why they get "hey, that is ambiguous"
> error.

I forgot to quote this part.

> ... to resolve "branch" as "remotes/*/branch" if unique?

One of the reasons I do not think it is a good idea is, saying
"if unique" makes it sound as if it is sane, but it forgets that
what confusion it is bringing into the picture when not unique.

If somebody says "git show master", obviously it would be found
under refs/heads/, and most likely there would be a tracking
branch refs/remotes/origin/master if you are not the project
lead, and if you work on more than one machines using
mothership-satellites configuration, you would probably have
refs/remotes/note/master and refs/remotes/laptop/master on your
mothership machine.  Now, "master" is not unique, but I do not
think we would want to complain "Gaah, master is not unique!  If
you mean heads/master, say so".

So addition to "if unique", we need another DWIM rule that says
"refs/heads/branch" trumps even when there are branch elsewhere
and prevents ambiguity rule from triggering.

And that is only one example I can think of in 10 minutes while
watching TV sitting next to my wife, without thinking much about
git X-<.  Who knows what other additional confusion we are
talking about?  That is what I fear most.

Re: Difficulties in advertising a new branch to git newbies

[Jeff King]

On Mon, Feb 05, 2007 at 11:25:49PM -0800, Junio C Hamano wrote:

> So addition to "if unique", we need another DWIM rule that says
> "refs/heads/branch" trumps even when there are branch elsewhere
> and prevents ambiguity rule from triggering.

FWIW, the patch I just posted allows all existing lookups to trump
refs/remotes/*/%s, but will complain of ambiguities between remotes.
But please don't take my patch as a vote for this being sane. :) I just
wanted to give Carl something to play with.

-Peff

Re: Difficulties in advertising a new branch to git newbies

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 2167 bytes --]

On Mon, 05 Feb 2007 22:37:42 -0800, Junio C Hamano wrote:
> Carl Worth <cworth@cworth.org> writes:
>
> > So, could we fix this so that a remote branch name will resolve
> > without the "origin/" prefix if it is not ambiguous?
>
> I am fairly negative on this one, especially I do not think the
> symptom deserves to be described with the word "fix".  DWIM is
> good, but it has bounds, and this particular one feels it is
> slightly on the other side of the boundary.

I can accept that argument.

With "fix" I was referring to the backwards-compatibility problem,
(that I don't have a way to give branch checkout instructions to users
that will work for both 1.5 and pre-1.5 versions of git). As is, if
I provide instructions that don't match the version the user has, then
the user will see a rather confusing message:

	git checkout: updating paths is incompatible with switching branches/forcing
	Did you intend to checkout 'origin/8801' which can not be resolved as commit?

[And perhaps the message above is evidence for too much DWIM in the
interface already---that checkout will accept either a revision
specifier or a path name and do fairly distinct operations depending
on which it gets.]

If my tail-matching-for-remotes idea won't fly, are there any other
suggestions for a way to provide instructions for this step that would
work across both 1.4 and 1.5 versions of git?

> If you add another DWIM rule, then I suspect that you would have
> harder time explaining why they get "hey, that is ambiguous"
> error.

Well, ideally git would explain the ambiguity with something like
this:

	There are multiple "proposed-fix" remote-tracking
	branches. Please specify which you would like:

		origin/proposed-fix
		something-else/proposed-fix

And I would think that this would not even be surprising since the
user would not get into this situation by default, but would actually
have to have added an additional something-else remote before being
able to get this kind of ambiguity.

But, like I said, I'm glad to accept that the tail-matching idea is a
bad idea. Feel free to drop that on the floor. I'm more interested in
the compatibility issue.

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Difficulties in advertising a new branch to git newbies

[Junio C Hamano]

Carl Worth <cworth@cworth.org> writes:

> On Mon, 05 Feb 2007 22:37:42 -0800, Junio C Hamano wrote:
>> Carl Worth <cworth@cworth.org> writes:
>>
>> > So, could we fix this so that a remote branch name will resolve
>> > without the "origin/" prefix if it is not ambiguous?
>>
>> I am fairly negative on this one, especially I do not think the
>> symptom deserves to be described with the word "fix".  DWIM is
>> good, but it has bounds, and this particular one feels it is
>> slightly on the other side of the boundary.
>
> I can accept that argument.
>
> With "fix" I was referring to the backwards-compatibility problem,
> (that I don't have a way to give branch checkout instructions to users
> that will work for both 1.5 and pre-1.5 versions of git).

If you tell your users to --use-separate-remote in the "git
clone" instruction, would that solve your backward compatibility
problem?

Re: Difficulties in advertising a new branch to git newbies

[Carl Worth]

[-- Attachment #1: Type: text/plain, Size: 259 bytes --]

On Tue, 06 Feb 2007 11:14:03 -0800, Junio C Hamano wrote:
> If you tell your users to --use-separate-remote in the "git
> clone" instruction, would that solve your backward compatibility
> problem?

Ah, yes. That should actually do the trick.

Thanks,

-Carl

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: Difficulties in advertising a new branch to git newbies

[Jakub Narebski]

Carl Worth wrote:

> On Tue, 06 Feb 2007 11:14:03 -0800, Junio C Hamano wrote:
>> If you tell your users to --use-separate-remote in the "git
>> clone" instruction, would that solve your backward compatibility
>> problem?
> 
> Ah, yes. That should actually do the trick.

Actually git has this option removed (at least from docs; perhaps it is
simply no-op).

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Difficulties in advertising a new branch to git newbies

[Jeff King]

On Mon, Feb 05, 2007 at 09:51:19PM -0800, Carl Worth wrote:

> I can imagine the resolution rules are already fairly complicated, (I
> don't even know what they all are already). But when there is no
> ambiguity, and when the behavior would be backwards compatible to git
> before separate-remotes, is there any reason this would be a bad idea?

I'm not convinced that the complication is a good idea.  However, if you
would like to play with it, a patch is below (it depends on my 'add
utility functions for enumerating remotes' patch, which I just posted).

-- >8 --
sha1_name: match refs in 'refs/remotes/*/%s'

If no other matches are found for a ref, then look for it in every defined
remote. This will not complain of ambiguity, since we only do the lookup if
no other ref matches.
---
 sha1_name.c |   37 +++++++++++++++++++++++++++++++++++++
 1 files changed, 37 insertions(+), 0 deletions(-)

diff --git a/sha1_name.c b/sha1_name.c
index d77f770..d9fe107 100644
--- a/sha1_name.c
+++ b/sha1_name.c
@@ -5,6 +5,7 @@
 #include "blob.h"
 #include "tree-walk.h"
 #include "refs.h"
+#include "remotes.h"
 
 static int find_short_object_filename(int len, const char *name, unsigned char *sha1)
 {
@@ -235,6 +236,30 @@ static int ambiguous_path(const char *path, int len)
 	return slash;
 }
 
+struct match_ref_in_remote_data {
+	const char *ref;
+	int ref_len;
+	int count;
+	unsigned char *sha1;
+	char *resolved;
+};
+static int match_ref_in_remote(const char *remote, void *data)
+{
+	struct match_ref_in_remote_data *md = data;
+	unsigned char sha1_from_ref[20];
+	const char *r;
+
+	r = resolve_ref(
+		mkpath("refs/remotes/%s/%.*s", remote, md->ref_len, md->ref),
+		md->count ? sha1_from_ref : md->sha1,
+		1, NULL);
+	if (r) {
+		if (!md->count++)
+			md->resolved = xstrdup(r);
+	}
+	return 0;
+}
+
 static const char *ref_fmt[] = {
 	"%.*s",
 	"refs/%.*s",
@@ -264,6 +289,18 @@ int dwim_ref(const char *str, int len, unsigned char *sha1, char **ref)
 				break;
 		}
 	}
+
+	if (!refs_found) {
+		struct match_ref_in_remote_data md;
+		md.ref = str;
+		md.ref_len = len;
+		md.count = 0;
+		md.sha1 = sha1;
+		for_each_remote(match_ref_in_remote, &md);
+		refs_found = md.count;
+		*ref = md.resolved;
+	}
+
 	return refs_found;
 }
 
-- 
1.5.0.rc3.554.ga40e-dirty

Re: Difficulties in advertising a new branch to git newbies

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> sha1_name: match refs in 'refs/remotes/*/%s'
>
> If no other matches are found for a ref, then look for it in every defined
> remote. This will not complain of ambiguity, since we only do the lookup if
> no other ref matches.

I think the abstraction is wrong -- why do you even need to
iterate over .git/remotes (and .git/config remote.*) when the
only thing this cares about is refs under refs/remotes/*
hierarchy?

Or am I missing something blatantly obvious?

Re: Difficulties in advertising a new branch to git newbies

[Jeff King]

On Mon, Feb 05, 2007 at 11:46:19PM -0800, Junio C Hamano wrote:

> I think the abstraction is wrong -- why do you even need to
> iterate over .git/remotes (and .git/config remote.*) when the
> only thing this cares about is refs under refs/remotes/*
> hierarchy?

Well, you obviously can't look in the directory because of packed refs.
You can enumerate all refs with for_each_remote_ref and try to match
against "refs/remotes/*/$ref". But how do you handle '/' in a remote
name or a branch name?  If I have a remote "foo/bar" with branch "baz",
should I match it while looking up "bar/baz"? What about having the
remote "foo" and the branch "bar/baz"? Should a lookup for "baz" find
that?

If I'm just given the collapsed "remote/branch" text, I don't know which
parts are remote and which parts are branch, unless I make the
assumption that remotes have no '/' in them (which I did not think we
were making).

-Peff

Re: Difficulties in advertising a new branch to git newbies

[Nicolas Pitre]

On Tue, 6 Feb 2007, Jeff King wrote:

> I'm not convinced that the complication is a good idea.  However, if you
> would like to play with it, a patch is below (it depends on my 'add
> utility functions for enumerating remotes' patch, which I just posted).


Your patch forgot to add the equivalent handling to dwim_log().


Nicolas