On Mon, 23 Apr 2007 22:15:04 -0700, Junio C Hamano wrote:
> Linus Torvalds <torvalds@xxxxxxxxxxxxxxxxxxxx> writes:
>
> > I'd personally be ok with a
> >
> > git clone --default=<branch> <url>
...
> If Carl is also happy with the syntax, we can conclude this
> discussion and:
>
> (1) have that as an enhancement to git-clone;
I think it's a useful enhancement. It would let me at least document
something like "tracking this project's stable branch" with a single
command, which I think is useful. But I don't know that I would be
totally happy yet. :-)
So please allow me to comment on the syntax a bit. Linus, you claimed
that <url>#<branch> isn't "unixy" enough for your taste. What does
that mean exactly? Is it that two logically independent things are
crammed into a single argument instead of being passed as second
arguments? Or something else?
Here's the reason I want both the URL and the branch to appear as a
single string, (but I don't really care about the precise syntax). I
really want to be able to say "see my branch at <string>" and have
that <string> be a complete and self-contained description of the
branch that can be used in several different ways including:
* Cloning a new repository to track that branch as the default
* Begin tracking that branch as a new branch within an existing
repository
* Viewing that branch's history in a web browser.
So in my dream world I'd publish a single URL+branch string that could
be fed directly to "git clone", something like "git track", or to a web
browser and the user would get exactly what was desired in all
cases. (As for http:// vs. git:// in the URL, I hope someone could
recommend the right magic to make things efficient in my dream world.)
So that idea also addresses the problem that Linus had with adding
some special "tracking" feature that would only be available for a
single branch and only at the time of clone. Of course that would be
undesirable, and that's why I've been talking about something like
"git track" to add the exact same functionality for tracking
subsequent branches after the clone.
When I last mentioned "git track", Junio pointed out that the existing
"git remote add <remote> URL" and "git checkout --track -b <branch>
<remote>/<branch>"[*] is more powerful anyway. I totally agree that
it's great to be able to add a remote like this, and to be able to
then use the <remote> alias to refer to the URL.
But the whole "git remote add" doesn't help and actually gets in the
way in the use case I'm trying to address. The problem is that if the
user has already created a remote alias for the URL I'm advertising, I
can't take advantage of that in my instructions since I don't know
what local name the user used for it.
Here's the kind of email I'd like to be able to write in my dream
world:
[1] I've just written some very fancy feature for our cool project
which you can see at <string> and clone or track with
git. Please try it out and give me feedback.
And from here, readers could paste <string> into a web browser to see
the branch's history, (I'd also like some branch-specific description
to appear), and also be presented with exact commands for cloning or
tracking the branch with git, ("git clone <string>" or "git track
<string>").
Even if the user didn't view the URL I gave in a web browser, there's
enough detail in my message to guess that "git clone <string>" and
"git track <string>" would be useful commands. Or without guessing
required, users would learn this after seeing the commands once or
twice in a web browser or whatever.
So in my dream world, a sentence like the above gives any user all the
information they need to start using git to get at my code. And notice
that my text gets to focus on my features and my project which is what
I care about in a message like this, and doesn't get bogged down in
sharing details about how to use git.
So compare the current situation with my dream world. The closest I
can get know is something like:
[2] I've just written some very fancy feature for our cool project
which you can see in gitweb at <gitweburl>. To track this
branch, do "git remote add cworth <url>; git checkout --track
-b <branch> cworth/<branch>" if you already have some clone of
our project. Otherwise do "git clone <url>; git checkout
--track -b <branch>". Please try it out and give me feedback.
So adding "clone --default" would help shorten the last command, but
wouldn't really help simplify the rest of this stuff. And it's really
all noise when what I want to be talking about is my code, not the
syntax of various git commands.
Now, someone might complain that I'm setting up a strawman with a
paragraph like that---that I'm throwing too much git talk into that
paragraph and that something more realistic with current git would
look like this:
[3] I've just written some very fancy feature for our cool project
which is available in the <branch> branch at <url>. Please try
it out and give me feedback.
I agree that that paragraph is more like what people are actually
doing with git-based projects today. But this paragraph is definitely
not as functional as my dream-world paragraph. What I don't like about
this one is how much knowledge this assumes on the part of the
user. If the user wants to see things in gitweb, they'll have to know
how to construct a URL for that. If they want to start tracking the
branch in an existing clone, they'll have to know the "remote add" and
"checkout --track" commands to do that.
Some people do know all that stuff and keep it current in their
heads. Some people will have done this before but will have to dig in
their mental memory banks or re-check a git reference card before they
can get at the code. And plenty of people will have have never used
git at all so will have to go learn about it. Where to go to learn?
There are enough obstacles there that some of these people won't be
successful and will never end up looking at my code, (which is not
what I want---I want as many people as possible to have an effortless
experience in getting at my code). And there are enough obstacles
there that even those who do make it through can easily get the
impression that "git is hard".
The only way I know to avoid those obstacles is to do like I did in
paragraph [2] and at least give the user all the pointers they need so
that they don't need to look anything up. But there again, there's so
much "git speak" that it still looks hard, and it definitely distracts
from what I'm really wanting to talk about.
This is what I'm referring to in the subject where I say that I'd like
git to be able to disappear into the background when I'm talking about
my code.
Does that description help you understand what I'm looking for when I
propose a new syntax for <url> plus <branch> that could be accepted by
both "clone" and also propose a new "track" command that could accept
the same syntax?
-Carl
[*] I don't know if that command is exactly right---there is a lot to
have to remember to put that command together, (and in a precise
order!), which is another reason I think the current approach is much
harder than it should be.
Attachment:
pgpe1O7eu0Md2.pgp
Description: PGP signature