From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=0.0 required=5.0 tests=DKIM_SIGNED,DKIM_VALID autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 28460 invoked from network); 1 Oct 2023 23:39:16 -0000 Received: from 9front.inri.net (168.235.81.73) by inbox.vuxu.org with ESMTPUTF8; 1 Oct 2023 23:39:16 -0000 Received: from pb-smtp21.pobox.com ([173.228.157.53]) by 9front; Sun Oct 1 19:34:43 -0400 2023 Received: from pb-smtp21.pobox.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id 4543224A95 for <9front@9front.org>; Sun, 1 Oct 2023 19:34:38 -0400 (EDT) (envelope-from unobe@cpan.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=message-id :to:subject:date:from:in-reply-to:mime-version:content-type :content-transfer-encoding; s=sasl; bh=39iYViHMKmE1HgomH2qKQWxHb Cw5MvDcugWpS48DxTU=; b=cx8yzTAbkfKZcjA/gZK1ong1l8MDsMlbFOsqb2D6K ePuiU3maIgk0paMvWOfDISKiioIzt82Rc1StDdVVV6RcPi1wlA7FUkKai0l7Nqc5 4fcgES1cn+auZmRIxFy4D3nUz0+n8/KaQYI2UWAtiSozZYN6GPqHT3K0sDVmyjTa q8= Received: from pb-smtp21.sea.icgroup.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id 3DC6924A94 for <9front@9front.org>; Sun, 1 Oct 2023 19:34:38 -0400 (EDT) (envelope-from unobe@cpan.org) Received: from strider.localdomain (unknown [75.237.252.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pb-smtp21.pobox.com (Postfix) with ESMTPSA id 81A8F24A92 for <9front@9front.org>; Sun, 1 Oct 2023 19:34:03 -0400 (EDT) (envelope-from unobe@cpan.org) Message-ID: To: 9front@9front.org Date: Sun, 01 Oct 2023 16:34:00 -0700 From: unobe@cpan.org In-Reply-To: MIME-Version: 1.0 Content-Type: text/plain; charset="US-ASCII" Content-Transfer-Encoding: 7bit X-Pobox-Relay-ID: 018726E8-60B3-11EE-8176-A19503B9AAD1-09620299!pb-smtp21.pobox.com List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: blockchain firewall AJAX over ActivityPub markup-based callback frontend Subject: Re: [9front] [PATCH] git: add missing usages for subcommands Reply-To: 9front@9front.org Precedence: bulk Quoth ori@eigenstate.org: > Quoth unobe@cpan.org: > > Quoth ori@eigenstate.org: > > > these were intentionally ommitted; you shouldn't need to use > > > them. They exist for scripts like 'git/commit', 'git/push', and > > > 'git/pull'. > > > > Thanks, Ori. I didn't realize that programs existing in the > > distribution shouldn't be documented. > > > > Two follow-ups: > > > > 1) Is that something that is standard and I've just never realized it? > > Not sure about 'standard'; it's a judgement call. > > I wouldn't mind having some form of documentation, but > putting them in the main git manpage just confuses the > user on how to do things, IMO. What if, in the long-form area that expanded on the different git programs, the ones which aren't meant to be used directly are mentioned as such? For me, some documentation of all programs is more useful than none, even ones meant for internal-use only? Something like this at the end: "Git/get, git/repack, git/save, and git/send are primarily internal commands, and therefore not documented beyond their usage lines above and their own code." > It's the same reason that debug flags are typically not > documented; if you're interacting with them, you're > typically already in the code. Do you mean the debug flag isn't documented in the 'usage:' output, or in the man page? I know debug flags are documented in quite a few programs (viz., mothra, doc2txt, gzip, proof, and ssh come to mind) so just trying to understand what is typical and what is not. I don't think its a foolish consistency to document them where they're available, particularly if all they're doing is providing output to stderr or what-not: without even looking at the code, some debug output is useful to a passerby. > > > 2) I didn't include git/hist in the doc patch: that's a "shouldn't > > need to use" program as well? > > No, that's one that's quite useful; it's basically > git blame on a budget (because it's honesty a pain > in the ass to implement 'blame'. > Ah, okay, good to know! I had been wondering what the (semi-)corollary to git/blame was!