From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carl Worth Subject: Making git disappear when talking about my code (was: Re: GIT vs Other: Need argument) Date: Wed, 25 Apr 2007 06:12:32 -0700 Message-ID: <87mz0w7g3j.wl%cworth@cworth.org> References: <20070417104520.GB4946@moonlight.home> <8b65902a0704170841q64fe0828mdefe78963394a616@mail.gmail.com> <200704171818.28256.andyparkins@gmail.com> <20070417173007.GV2229@spearce.org> <462521C7.2050103@softax.com.pl> <4627ABBB.8060709@softax.com.pl> <877is29b1l.wl%cworth@cworth.org> <7vps5ud91x.fsf@assigned-by-dhcp.cox.net> <87vefm7l6g.wl%cworth@cworth.org> <7v1wiabbfr.fsf@assigned-by-dhcp.cox.net> Mime-Version: 1.0 (generated by SEMI 1.14.6 - "Maruoka") Content-Type: multipart/signed; boundary="pgp-sign-Multipart_Wed_Apr_25_06:12:23_2007-1"; micalg=pgp-sha1; protocol="application/pgp-signature" Content-Transfer-Encoding: 7bit Cc: Linus Torvalds , Marcin Kasperski , git@vger.kernel.org To: Junio C Hamano X-From: git-owner@vger.kernel.org Wed Apr 25 15:13:20 2007 Return-path: Envelope-to: gcvg-git@gmane.org Received: from vger.kernel.org ([209.132.176.167]) by lo.gmane.org with esmtp (Exim 4.50) id 1HghJ9-0001Ed-29 for gcvg-git@gmane.org; Wed, 25 Apr 2007 15:13:19 +0200 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S2992731AbXDYNMl (ORCPT ); Wed, 25 Apr 2007 09:12:41 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S2992750AbXDYNMl (ORCPT ); Wed, 25 Apr 2007 09:12:41 -0400 Received: from theworths.org ([217.160.253.102]:47772 "EHLO theworths.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S2992741AbXDYNMj (ORCPT ); Wed, 25 Apr 2007 09:12:39 -0400 Received: (qmail 30353 invoked from network); 25 Apr 2007 09:12:32 -0400 Received: from localhost (HELO raht.cworth.org) (127.0.0.1) by localhost with SMTP; 25 Apr 2007 09:12:32 -0400 In-Reply-To: <7v1wiabbfr.fsf@assigned-by-dhcp.cox.net> User-Agent: Wanderlust/2.14.0 (Africa) Emacs/21.4 Mule/5.0 (SAKAKI) Sender: git-owner@vger.kernel.org Precedence: bulk X-Mailing-List: git@vger.kernel.org Archived-At: --pgp-sign-Multipart_Wed_Apr_25_06:12:23_2007-1 Content-Type: text/plain; charset=US-ASCII On Mon, 23 Apr 2007 22:15:04 -0700, Junio C Hamano wrote: > Linus Torvalds writes: > > > I'd personally be ok with a > > > > git clone --default= ... > 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 # 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 " and have that 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 URL" and "git checkout --track -b /"[*] 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 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 and clone or track with git. Please try it out and give me feedback. And from here, readers could paste 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 " or "git track "). 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 " and "git track " 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 . To track this branch, do "git remote add cworth ; git checkout --track -b cworth/" if you already have some clone of our project. Otherwise do "git clone ; git checkout --track -b ". 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 at . 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 plus 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. --pgp-sign-Multipart_Wed_Apr_25_06:12:23_2007-1 Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) iD8DBQBGL1O/6JDdNq8qSWgRAiNHAJ0a9xEmStT2UNV8fSf6G0CyNynIHwCfb6I5 vNATpBGb3gkEjfdlqlqXZr0= =MkHb -----END PGP SIGNATURE----- --pgp-sign-Multipart_Wed_Apr_25_06:12:23_2007-1--