[PATCH] doc/fsck: discuss mix of --connectivity-only and --dangling

[Jeff King <peff@peff.net>]

The --connectivity-only option avoids opening every object, and instead
just marks reachable objects with a flag, and compares this to the set
of all objects. This strategy is discussed in more detail in 3e3f8bd608
(fsck: prepare dummy objects for --connectivity-check, 2017-01-17).

This means that we report _every_ unreachable object as dangling.
Whereas in a full fsck, we'd have actually opened and parsed each of
those unreachable objects, marking their child objects with the USED
flag, to mean "this was mentioned by another object". And thus we can
report only the tip of an unreachable segment of the object graph as
dangling.

You can see this difference with a trivial example:

  tree=$(git hash-object -t tree -w /dev/null)
  one=$(echo one | git commit-tree $tree)
  two=$(echo two | git commit-tree -p $one $tree)

Running `git fsck` will report only $two as dangling, but with
--connectivity-only, both commits (and the tree) are reported.

We could make the two cases work identically by taking a separate pass
over the unreachable objects, parsing them and marking objects they
refer to as USED. That would still avoid parsing any blobs, but we'd pay
the cost to access any unreachable commits and trees. Since the point of
--connectivity-only is to quickly report whether all reachable objects
are present, I'd argue that it's not worth slowing it down to produce
a better-analyzed dangling list.

Instead, let's document this somewhat surprising property of
connectivity-only. If somebody really wants to the extra analysis, we
can add a separate option to enable it.

Signed-off-by: Jeff King <peff@peff.net>
---
 Documentation/git-fsck.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt
index 55950d9eea..02ce7c6282 100644
--- a/Documentation/git-fsck.txt
+++ b/Documentation/git-fsck.txt
@@ -65,6 +65,10 @@ index file, all SHA-1 references in `refs` namespace, and all reflogs
 	Check only the connectivity of tags, commits and tree objects. By
 	avoiding to unpack blobs, this speeds up the operation, at the
 	expense of missing corrupt objects or other problematic issues.
+	Note that this also skips some analysis of unreachable objects,
+	meaning that Git will report the full list of unreachable
+	objects as dangling (unless `--no-dangling` was used), rather
+	than the tips of unreachable segments of history.
 
 --strict::
 	Enable more strict checking, namely to catch a file mode
-- 
2.21.0.675.g01c085a870