From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Greg A. Woods" Subject: Re: Git documentation consistency (was: "git merge" merges too much!) Date: Wed, 02 Dec 2009 20:21:39 -0500 Message-ID: References: <20091129051427.GA6104@coredump.intra.peff.net> <20091202200904.GA7631@coredump.intra.peff.net> Reply-To: The Git Mailing List Mime-Version: 1.0 (generated by SEMI 1.14.6 - "Maruoka") Content-Type: multipart/signed; boundary="pgp-sign-Multipart_Wed_Dec__2_20:21:38_2009-1"; micalg=pgp-sha1; protocol="application/pgp-signature" Content-Transfer-Encoding: 7bit To: The Git Mailing List X-From: git-owner@vger.kernel.org Thu Dec 03 02:21:54 2009 Return-path: Envelope-to: gcvg-git-2@lo.gmane.org Received: from vger.kernel.org ([209.132.176.167]) by lo.gmane.org with esmtp (Exim 4.50) id 1NG0OG-0006NV-Jp for gcvg-git-2@lo.gmane.org; Thu, 03 Dec 2009 02:21:52 +0100 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754304AbZLCBVj (ORCPT ); Wed, 2 Dec 2009 20:21:39 -0500 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1754291AbZLCBVj (ORCPT ); Wed, 2 Dec 2009 20:21:39 -0500 Received: from most.weird.com ([204.92.254.2]:57496 "EHLO most.weird.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754200AbZLCBVh (ORCPT ); Wed, 2 Dec 2009 20:21:37 -0500 Received: from once.weird.com ([204.92.254.13] port=58306) by most.weird.com([204.92.254.2] port=25) via TCP with esmtp (5315 bytes) (sender: ) (ident using rfc1413) id for ; Wed, 2 Dec 2009 20:21:42 -0500 (EST) (Smail-3.2.0.122-Pre 2005-Nov-17 #1 built 2009-Feb-3) In-Reply-To: <20091202200904.GA7631@coredump.intra.peff.net> User-Agent: Wanderlust/2.15.6 (Almost Unreal) SEMI/1.14.6 (Maruoka) FLIM/1.14.7 (=?ISO-8859-4?Q?Sanj=F2?=) APEL/10.7 Emacs/22.3 (i386--netbsdelf) MULE/5.0 (SAKAKI) X-Face: ;j3Eth2XV8h1Yfu*uL{<:dQ$#E[DB0gemGZJ"J#4fH*][ lz;@-iwMv_u\6uIEKR0KY"=MzoQH#CrqBN`nG_5B@rrM8,f~Gr&h5a\= X-Mailing-List: git@vger.kernel.org Archived-At: --pgp-sign-Multipart_Wed_Dec__2_20:21:38_2009-1 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable At Wed, 2 Dec 2009 15:09:04 -0500, Jeff King wrote: Subject: Re: "git merge" merges too much! >=20 > I find git is much simpler to use and understand if you start "at the > bottom" with the basic concepts (because for the most part, git is > really a set of tools for manipulating the few basic data structures). I think that's the problem actually -- I don't really want to know too much about how it works under the hood (yet), I just want to use it in the most effective way for my purposes. There's lots of talk about using Git as the basis for a true high-level VCS and SCM system, yet it doesn't look to me that anyone has created such a VCS or SCMS using Git. > I skimmed it and didn't see any inconsistency. If you have something > specific in mind, please point it out so we can fix it. I think anyone who's been participating on this list for any significant amount of time is far too close to the subject to be able to serve as a candid independent technical editor who could really help clean things up and make the documentation much more consistent. Obviously such an editor would also require the help of experts at all the details too. :-) Unfortunately I'm not a very good technical editor, and I don't really have time to devote to doing such editing of documentation either. > > (git-log(1) is worse than ls(1) for having too many options, but worst > > of all in the release I'm still using it doesn't respond sensibly nor > > consistently with other commands when given the "-?" option.) >=20 > $ ls -? > ls: invalid option -- '?' > Try `ls --help' for more information. Please keep in mind all the world is not GNU: $ ls -? ls: unknown option -- ? usage: ls [-AaBbCcdFfghikLlmnopqRrSsTtuWwx1] [file ...] My point was that _most_ other Git sub-commands already do respond to "-?" sensibly with real, helpful, information; usually a summary of the command options and parameters. I.e. this is yet another form of inconsistency in "documentation" in Git. :-) The reference to "ls" was just as a comparison with it's somewhat extensive variety of options. In fact "git log" is way more complex than "ls" because its parameters are not all just simple flags like those for "ls" -- they often have their own parameters too. > $ git log -h > usage: git log [] [..] [[--] ...] > or: git show [options] ... Indeed, so why the heck can't it do something similar with '-?'. That's just sloppy programming, no? Most other commands know '-?', and despite the silliness with GNU Ls, use of '-?' to request summary usage information is pretty much a de facto standard for unix commands. Your point about mentioning "--help" in the summary usage information is a good one though -- especially for a command with a very complex set of command-line parameters. However that alone isn't sufficient -- users still need the summary as that alone helps trigger associations and may be sufficient to allow a user to proceed quickly to get the command to do what they want. (the whole "fatal: not a git repository" error for "git foo -[h?]" handling is also a rather silly one -- but I guess when something grows quickly and from many inputs there's not always time to keep some of these basic things clean and consistent) --=20 Greg A. Woods Planix, Inc. +1 416 218 0099 http://www.planix.com/ --pgp-sign-Multipart_Wed_Dec__2_20:21:38_2009-1 Content-Type: application/pgp-signature Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.9 (NetBSD) iD8DBQBLFxKiZn1xt3i/9H8RAsqGAKCK3s6T+DAc3P6qytAmtZ9COaiTDACeOGoO JcAQvPwgE2XvSK3AhKas7zo= =spP4 -----END PGP SIGNATURE----- --pgp-sign-Multipart_Wed_Dec__2_20:21:38_2009-1--