git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Jeff King <peff@peff.net>
To: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Cc: git@vger.kernel.org, Junio C Hamano <gitster@pobox.com>,
	Adam Roben <aroben@apple.com>,
	Bryan Larsen <bryan.larsen@gmail.com>,
	Matthias Urlichs <smurf@smurf.noris.de>,
	Eric Sunshine <sunshine@sunshineco.com>
Subject: Re: [PATCH 3/3] hash-object doc: point to ls-files and rev-parse
Date: Wed, 22 May 2019 01:15:23 -0400	[thread overview]
Message-ID: <20190522051523.GC29933@sigill.intra.peff.net> (raw)
In-Reply-To: <20190520215312.10363-4-avarab@gmail.com>

On Mon, May 20, 2019 at 11:53:12PM +0200, Ævar Arnfjörð Bjarmason wrote:

> Amend the intro to note that it's better to ask the index about files
> already tracked by it.
> 
> I've seen uses of this in the wild where the use-case was finding
> object IDs for files found in a freshly cloned repo, i.e. something
> like "git ls-files | git hash-object --stdin-paths".

This example left me scratching my head, because it seems like such a
bad way to accomplish the goal that I had trouble figuring out what the
goal was in the first place.

Of course I am pretty familiar with Git, so my mindset is not
necessarily the same as the average reader of the manpage. But the
suggested documentation really seems to me to be warning about a
convoluted use case that most people would not come up with in the first
place.

And adding it in the introductory text means that people are more likely
to read and be confused by it, when they are really just looking to find
details on more mundane usage.

Or put another way: I could come up with a hundred bad ways to script
Git, but we are probably better off enumerating the _good_ ways to do
so, rather than listing the bad ways and leaving the user to figure out
what's left.

So I'm mildly negative on this patch.

-Peff

      reply	other threads:[~2019-05-22  5:15 UTC|newest]

Thread overview: 12+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-05-20 21:53 [PATCH 0/3] hash-object doc: small fixes Ævar Arnfjörð Bjarmason
2019-05-20 21:53 ` [PATCH 1/3] hash-object doc: stop mentioning git-cvsimport Ævar Arnfjörð Bjarmason
2019-05-22  4:57   ` Jeff King
2019-05-20 21:53 ` [PATCH 2/3] hash-object doc: elaborate on -w and --literally promises Ævar Arnfjörð Bjarmason
2019-05-22  5:08   ` Jeff King
2019-05-24 10:04     ` Jakub Narebski
2019-05-24 10:12       ` Ævar Arnfjörð Bjarmason
2019-05-28  6:06         ` Jeff King
2019-05-28 16:56       ` Junio C Hamano
2019-05-28 16:49   ` Junio C Hamano
2019-05-20 21:53 ` [PATCH 3/3] hash-object doc: point to ls-files and rev-parse Ævar Arnfjörð Bjarmason
2019-05-22  5:15   ` Jeff King [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190522051523.GC29933@sigill.intra.peff.net \
    --to=peff@peff.net \
    --cc=aroben@apple.com \
    --cc=avarab@gmail.com \
    --cc=bryan.larsen@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=smurf@smurf.noris.de \
    --cc=sunshine@sunshineco.com \
    --subject='Re: [PATCH 3/3] hash-object doc: point to ls-files and rev-parse' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).