Turn git survey into a deprecated shim over git repo structure

Documentation/config.adoc

@@ -511,6 +511,8 @@ include::config/remotes.adoc[]
 
 include::config/repack.adoc[]
 
+include::config/repo.adoc[]
+
 include::config/rerere.adoc[]
 
 include::config/revert.adoc[]

Documentation/config/repo.adoc

@@ -0,0 +1,11 @@
+repo.structure.*::
+	These variables adjust the default behavior of the
+	`git repo structure` command.
++
+--
+	top::
+		This integer value implies `--top=<N>`, specifying the
+		number of largest paths to report in each detail table.
+		Must be non-negative; defaults to `0`, which disables the
+		detail tables.
+--

Documentation/git-repo.adoc

@@ -10,7 +10,7 @@ SYNOPSIS
 [synopsis]
 git repo info [--format=(lines|nul) | -z] [--all | <key>...]
 git repo info --keys [--format=(lines|nul) | -z]
-git repo structure [--format=(table|lines|nul) | -z]
+git repo structure [<options>]
 
 DESCRIPTION
 -----------
@@ -56,7 +56,7 @@ supported:
 `nul`:::
 	Similar to `lines`, but using a _NUL_ character after each value.
 
-`structure [--format=(table|lines|nul) | -z]`::
+`structure`::
 	Retrieve statistics about the current repository structure. The
 	following kinds of information are reported:
 +
@@ -65,6 +65,32 @@ supported:
 * Total inflated size of reachable objects by type
 * Total disk size of reachable objects by type
 * Largest reachable objects in the repository by type
+* Optionally, the top-_N_ largest paths by count, on-disk size, and
+  inflated size (see `--top` below)
++
+By default every reference enumerated by `for-each-ref` contributes to
+the counts and object walk. Use `--ref-filter` to narrow the scope.
+
+	`--ref-filter=<pattern>`;;
+		Only count references whose full name matches one of the
+		given <pattern>s, and only seed the object walk from
+		those references. The option is repeatable; multiple
+		patterns form a union. Patterns use the same `wildmatch`
+		semantics as `git for-each-ref`'s positional arguments,
+		so `*` does not cross `/`. Examples:
+		`--ref-filter='refs/heads/*'` for local branches,
+		`--ref-filter='refs/tags/v*'` for release tags,
+		`--ref-filter='refs/remotes/origin/*'` for a single
+		remote's branches.
+
+	`--top=<n>`;;
+		Also report the _n_ largest paths in the repository,
+		separately for trees and blobs and separately ranked by
+		object count, on-disk size, and inflated size. Defaults
+		to `0`, which suppresses the detail tables. The default
+		can also be set via the `repo.structure.top` configuration
+		variable; an explicit `--top=<n>` on the command line
+		overrides the configured value.
 +
 The output format can be chosen through the flag `--format`. Three formats are
 supported:

Documentation/git-survey.adoc

@@ -8,11 +8,18 @@ git-survey - EXPERIMENTAL: Measure various repository dimensions of scale
 SYNOPSIS
 --------
 [verse]
-(EXPERIMENTAL!) 'git survey' <options>
+(DEPRECATED!) 'git survey' <options>
 
 DESCRIPTION
 -----------
 
+NOTE: `git survey` is being superseded by `git repo structure`. New
+deployments and new features should use `git repo structure`; its
+`--ref-filter=<pattern>` option subsumes the various `--branches`,
+`--tags`, and `--remotes` flags here, and `--top=<N>` provides the
+same detail tables. A future release will turn `git survey` into a
+thin shim over `git repo structure`. See linkgit:git-repo[1].
+
 Survey the repository and measure various dimensions of scale.
 
 As repositories grow to "monorepo" size, certain data shapes can cause