From mboxrd@z Thu Jan 1 00:00:00 1970 From: Carl Worth Subject: Re: A tour of git: the basics (and notes on some unfriendly messages) Date: Sat, 29 Sep 2007 20:38:45 -0700 Message-ID: <87d4w0styy.wl%cworth@cworth.org> References: <87ir5us82a.wl%cworth@cworth.org> <7v1wcinvth.fsf@gitster.siamese.dyndns.org> Mime-Version: 1.0 (generated by SEMI 1.14.6 - "Maruoka") Content-Type: multipart/signed; boundary="pgp-sign-Multipart_Sat_Sep_29_20:38:45_2007-1"; micalg=pgp-sha1; protocol="application/pgp-signature" Content-Transfer-Encoding: 7bit Cc: git@vger.kernel.org To: Junio C Hamano X-From: git-owner@vger.kernel.org Sun Sep 30 05:38:59 2007 Return-path: Envelope-to: gcvg-git-2@gmane.org Received: from vger.kernel.org ([209.132.176.167]) by lo.gmane.org with esmtp (Exim 4.50) id 1Ibpdx-0003r8-JB for gcvg-git-2@gmane.org; Sun, 30 Sep 2007 05:38:58 +0200 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753052AbXI3Dit (ORCPT ); Sat, 29 Sep 2007 23:38:49 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1752761AbXI3Dit (ORCPT ); Sat, 29 Sep 2007 23:38:49 -0400 Received: from olra.theworths.org ([82.165.184.25]:57786 "EHLO olra.theworths.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751273AbXI3Dis (ORCPT ); Sat, 29 Sep 2007 23:38:48 -0400 Received: from localhost (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id 94DBF431FB1; Sat, 29 Sep 2007 20:38:47 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 7QV7mXeKSJux; Sat, 29 Sep 2007 20:38:46 -0700 (PDT) Received: from raht.cworth.org (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id 208DF431FB0; Sat, 29 Sep 2007 20:38:46 -0700 (PDT) In-Reply-To: <7v1wcinvth.fsf@gitster.siamese.dyndns.org> 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_Sat_Sep_29_20:38:45_2007-1 Content-Type: text/plain; charset=US-ASCII On Fri, 28 Sep 2007 17:45:30 -0700, Junio C Hamano wrote: > Thanks for starting this. It was an interesting read. You're welcome. I hope it's useful for people. The original goal was to demonstrate that git is no harder to learn than mercurial. So that attempt is done, now, (whether successful or not, I can't really judge). Now, after getting some initial feedback, it's clear that the document could further be improved by focusing on the "git way" of doing things that aren't as natural in hg, (like multiple branches in a single repository). Rather than extending the current document, though, I think I'll just draw up on outline based on what I think would be a good order to introduce the topics. And then I'll see what text in the current user's guide could plug into that outline, and what pieces might be missing or could be improved. At least, that's my thoughts for now. I don't know if I'll get around to it though, (we'll have to see if I get annoyed into doing that work like I got annoyed into this first project). > "git help init" would give man page. The time when the short > help is given is when you mistype options, as in: > > $ git init --huh? Oh, and that's *really* short output. Just a summary of the command-line options and no description. If you look at "hg help" it has a middle-ground option which is little more than a brief description and a very small number of options. I think that's a useful thing to consider for "git help". Or, perhaps just carefully construct the man page so that this most important information is first. See "git help clone" for example which does have a better order than "git help init" in my opinion. Meanwhile, "git init --huh?" is totally appropriate in just printing usage information. That's really all you want to see if you forget the exact name of a particular command-line option. Trying a couple of random examples though, git could be better in some cases: $ git log --pretty=complete fatal: invalid --pretty format: complete That's a fairly specific error message, but no information on what I might have meant to say. A fix should be be quite simple, (presumably there's a list of --pretty options it just looped through and it might as well print them out). $ git log --format=fuller fatal: unrecognized argument: --format=fuller There's no usage given in this case at all. It should print some usage statement, hopefully containing --pretty. Admittedly, this one is *really* hard to fix entirely since there is a ridiculously large number of possible options to a command like "git log". But a aummary of the most common stuff should still help. Thanks for the various typo fixes. I've implemented those, (and the things submitted by others). There were some particularly bad markup problems where "git commit " was being misinterpreted and presented as "git commit" which was fairly disastrous for my intended meaning. Hopefully it's much better now. -Carl --pgp-sign-Multipart_Sat_Sep_29_20:38:45_2007-1 Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.6 (GNU/Linux) iD8DBQBG/xpF6JDdNq8qSWgRAiApAJ90YGbBimFMO3gSXDeXINFCzKtoJgCeMK+3 jbADQa+NR8Bq3OmQRaiTYVo= =3xnH -----END PGP SIGNATURE----- --pgp-sign-Multipart_Sat_Sep_29_20:38:45_2007-1--