git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
To: git@vger.kernel.org
Cc: "Junio C Hamano" <gitster@pobox.com>, "Jeff King" <peff@peff.net>,
	"Adam Roben" <aroben@apple.com>,
	"Bryan Larsen" <bryan.larsen@gmail.com>,
	"Matthias Urlichs" <smurf@smurf.noris.de>,
	"Eric Sunshine" <sunshine@sunshineco.com>,
	"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Subject: [PATCH 2/3] hash-object doc: elaborate on -w and --literally promises
Date: Mon, 20 May 2019 23:53:11 +0200	[thread overview]
Message-ID: <20190520215312.10363-3-avarab@gmail.com> (raw)
In-Reply-To: <20190520215312.10363-1-avarab@gmail.com>

Clarify the hash-object docs to explicitly note that the --literally
option guarantees that a loose object will be written, but that a
normal -w ("write") invocation doesn't.

At first I thought talking about "loose object" in the docs was a
mistake in 83115ac4a8 ("git-hash-object.txt: document --literally
option", 2015-05-04), but as is clear from 5ba9a93b39 ("hash-object:
add --literally option", 2014-09-11) this was intended all along.

As seen in 4dd1fbc7b1 ("Bigfile: teach "git add" to send a large file
straight to a pack", 2011-05-08) we'll otherwise not guarantee that we
write loose objects, so let's explicitly note that, using vague enough
language to leave the door open to any arbitrary future storage
format, not just loose objects and packs.

While I'm at it remove the mention of "--stdin" from the "--literally"
documentation. This wasn't correct, the "--literally" option combines
with any other option (e.g. "--stdin-paths"), not just "--stdin".

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/git-hash-object.txt | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt
index df9e2c58bd..100630d021 100644
--- a/Documentation/git-hash-object.txt
+++ b/Documentation/git-hash-object.txt
@@ -28,6 +28,12 @@ OPTIONS
 
 -w::
 	Actually write the object into the object database.
++
+No guarantees are made as to how the object is added to the database
+(e.g. whether as a loose object, or streamed to a pack), except in the
+case of the `--literally` option. How it's written may depend on
+heuristics such as the `core.bigFileThreshold` configuration variable
+(see linkgit:git-config[1]).
 
 --stdin::
 	Read the object from standard input instead of from a file.
@@ -53,10 +59,11 @@ OPTIONS
 	is always implied, unless the `--path` option is given.
 
 --literally::
-	Allow `--stdin` to hash any garbage into a loose object which might not
+	Allow for hashing arbitrary data which might not
 	otherwise pass standard object parsing or git-fsck checks. Useful for
 	stress-testing Git itself or reproducing characteristics of corrupt or
-	bogus objects encountered in the wild.
+	bogus objects encountered in the wild. When writing objects guarantees
+	that the written object will be a loose object, for ease of debugging.
 
 GIT
 ---
-- 
2.21.0.1020.gf2820cf01a


  parent reply	other threads:[~2019-05-20 21:53 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 ` Ævar Arnfjörð Bjarmason [this message]
2019-05-22  5:08   ` [PATCH 2/3] hash-object doc: elaborate on -w and --literally promises 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

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=20190520215312.10363-3-avarab@gmail.com \
    --to=avarab@gmail.com \
    --cc=aroben@apple.com \
    --cc=bryan.larsen@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=peff@peff.net \
    --cc=smurf@smurf.noris.de \
    --cc=sunshine@sunshineco.com \
    --subject='Re: [PATCH 2/3] hash-object doc: elaborate on -w and --literally promises' \
    /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).