doc: pack-objects: clarify --missing option

Commit Message

Han Young Aug. 8, 2024, 6:21 a.m. UTC

Since ee47243d76 (pack-objects: no fetch when allow-{any,promisor},
2020-08-05), we mention that --missing=allow-any and --missing=allow-promisor
do not fetch missing objects. But this is only true for missing objects
that are discovered during object traversal. We will still fetch
missing objects read from stdin.

Signed-off-by: Han Young <[e-mail]>
---
objects read from stdin ignore --missing option, if the repo has
promisor remote, we will try to fetch missing objects. Even if
the missing objects is not "EXPECTED promisor missing objects".
"--missing=allow-promisor" will not raise an error on such cases.

 Documentation/git-pack-objects.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

Comments

Patrick Steinhardt Aug. 8, 2024, 7:48 a.m. UTC | #1

On Thu, Aug 08, 2024 at 02:21:20PM +0800, Han Young wrote:
> Since ee47243d76 (pack-objects: no fetch when allow-{any,promisor},
> 2020-08-05), we mention that --missing=allow-any and --missing=allow-promisor
> do not fetch missing objects. But this is only true for missing objects
> that are discovered during object traversal. We will still fetch
> missing objects read from stdin.

I have to wonder whether this is intentional or a bug. It rather feels
like the latter to me. Let me Cc Chris, who has written most of the
infra of this feature.

Patrick

Patch

diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index e32404c6aa..0c1f86dabe 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -313,13 +313,14 @@  attempt to fetch missing objects will be made before declaring them missing.
 This is the default action.
 +
 The form '--missing=allow-any' will allow object traversal to continue
-if a missing object is encountered.  No fetch of a missing object will occur.
-Missing objects will silently be omitted from the results.
+if a missing object is encountered.  No fetch of a missing object will occur
+during object traversal. Missing objects will silently be omitted from the
+results.
 +
 The form '--missing=allow-promisor' is like 'allow-any', but will only
 allow object traversal to continue for EXPECTED promisor missing objects.
-No fetch of a missing object will occur.  An unexpected missing object will
-raise an error.
+No fetch of a missing object will occur during object traversal.
+An unexpected missing object will raise an error.
 
 --exclude-promisor-objects::
 	Omit objects that are known to be in the promisor remote.  (This