| Message ID | 20190520215312.10363-4-avarab@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | hash-object doc: small fixes | expand |
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
diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index 100630d021..077d83ec65 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -20,6 +20,13 @@ work tree), and optionally writes the resulting object into the object database. Reports its object ID to its standard output. When <type> is not specified, it defaults to "blob". +This command won't take the shortcut of seeing if the path(s) to be +hashed are present in the index, in which case their already computed +object ID could be retrieved by linkgit:git-ls-files[1] via the +`--stage` option, or by linkgit:git-rev-parse[1]. Use those instead of +e.g. `--stdin-paths` if the intent is to say find the blob object IDs +of checked-out files. + OPTIONS -------
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". Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> --- Documentation/git-hash-object.txt | 7 +++++++ 1 file changed, 7 insertions(+)