Merge branch 'jh/experimental-survey'

This topic branch brings in a new, experimental built-in command to
assess the dimensions of a local repository.

It is experimental and subject to change! It might grow new options,
change its output, or even be moved into `git diagnose --analyze` or
something like that.

The hope is that this command, which was inspired by `git sizer`
(https://github.com/github/git-sizer), will be helpful not only in
diagnosing issues with large repositories, but also in modeling what
shapes and sizes of repositories can be handled by Git (and as a
corollary: where Git needs to improve to be able to accommodate the
natural growth of repositories).

Signed-off-by: Johannes Schindelin <[email protected]>

Author: dscho

Documentation/config/survey.adoc

@@ -4,11 +4,44 @@ survey.*::
 	background with these options.
 +
 --
+	survey.namerev::
+		Boolean to show/hide `git name-rev` information for each
+		reported commit and the containing commit of each
+		reported tree and blob.
 	verbose::
 		This boolean value implies the `--[no-]verbose` option.
 	progress::
 		This boolean value implies the `--[no-]progress` option.
 	top::
 		This integer value implies `--top=<N>`, specifying the
 		number of entries in the detail tables.
+	showBlobSizes::
+		A non-negative integer value.  Requests details on the
+		<n> largest file blobs by size in bytes.  Provides a
+		default value for `--blob-sizes=<n>` in
+		linkgit:git-survey[1].
+	showCommitParents::
+		A non-negative integer value.  Requests details on the
+		<n> commits with the most number of parents.  Provides a
+		default value for `--commit-parents=<n>` in
+		linkgit:git-survey[1].
+	showCommitSizes::
+		A non-negative integer value.  Requests details on the
+		<n> largest commits by size in bytes.  Generally, these
+		are the commits with the largest commit messages.
+		Provides a default value for `--commit-sizes=<n>` in
+		linkgit:git-survey[1].
+	showTreeEntries::
+		A non-negative integer value.  Requests details on the
+		<n> trees (directories) with the most number of entries
+		(files and subdirectories).  Provides a default value
+		for `--tree-entries=<n>` in linkgit:git-survey[1].
+	showTreeSizes::
+		A non-negative integer value.  Requests details on the
+		<n> largest trees (directories) by size in bytes.  This
+		will set will usually be equal to the
+		`survey.showTreeEntries` set, but may be skewed by very
+		long file or subdirectory entry names.  Provides a
+		default value for `--tree-sizes=<n>` in
+		linkgit:git-survey[1].
 --

Documentation/git-survey.adoc

@@ -32,6 +32,10 @@ OPTIONS
 --progress::
 	Show progress.  This is automatically enabled when interactive.
 
+--[no-]name-rev::
+	Print `git name-rev` output for each commit, tree, and blob.
+	Defaults to true.
+
 Ref Selection
 ~~~~~~~~~~~~~
 
@@ -59,6 +63,32 @@ only refs for the given options are added.
 --other::
 	Add notes (`refs/notes/`) and stashes (`refs/stash/`) to the set.
 
+Large Item Selection
+~~~~~~~~~~~~~~~~~~~~
+
+The following options control the optional display of large items under
+various dimensions of scale.  The OID of the largest `n` objects will be
+displayed in reverse sorted order.  For each, `n` defaults to 10.
+
+--commit-parents::
+	Shows the OIDs of the commits with the most parent commits.
+
+--commit-sizes::
+	Shows the OIDs of the largest commits by size in bytes.  This is
+	usually the ones with the largest commit messages.
+
+--tree-entries::
+	Shows the OIDs of the trees with the most number of entries.  These
+	are the directories with the most number of files or subdirectories.
+
+--tree-sizes::
+	Shows the OIDs of the largest trees by size in bytes.  This set
+	will usually be the same as the vector of number of entries unless
+	skewed by very long entry names.
+
+--blob-sizes::
+	Shows the OIDs of the largest blobs by size in bytes.
+
 OUTPUT
 ------
 
@@ -78,6 +108,11 @@ Reachable Object Summary
 The reachable object summary shows the total number of each kind of Git
 object, including tags, commits, trees, and blobs.
 
+CONFIGURATION
+-------------
+
+include::config/survey.adoc[]
+
 GIT
 ---
 Part of the linkgit:git[1] suite