[PATCH 3/3] repo: add documentation for level-of-concern.
---
Documentation/config/repo.adoc | 60 ++++++++++++++++++++++++++++++++++++++++++
Documentation/git-repo.adoc | 27 +++++++++++++++++--
2 files changed, 85 insertions(+), 2 deletions(-)
diff --git a/Documentation/config/repo.adoc b/Documentation/config/repo.adoc
new file mode 100644
index 0000000000..ad16bdcc67
--- /dev/null
+++ b/Documentation/config/repo.adoc
@@ -0,0 +1,60 @@
+`repo.structure.concern.commit-count`::
+ Sets the value of the concern threshold for commit count.
+
+`repo.structure.concern.tree-count`::
+ Sets the value of the concern threshold for tree count.
+
+`repo.structure.concern.blob-count`::
+ Sets the value of the concern threshold for blob count.
+
+`repo.structure.concern.tag-count`::
+ Sets the value of the concern threshold for tag count.
+
+`repo.structure.concern.commit-size`::
+ Sets the value of the concern threshold for total commit size.
+
+`repo.structure.concern.tree-size`::
+ Sets the value of the concern threshold for total tree size.
+
+`repo.structure.concern.blob-size`::
+ Sets the value of the concern threshold for total blob size.
+
+`repo.structure.concern.tag-size`::
+ Sets the value of the concern threshold for total tag size.
+
+`repo.structure.concern.commit-inflated-size`::
+ Sets the value of the concern threshold for total size
+ of all inflated commits.
+
+`repo.structure.concern.tree-inflated-size`::
+ Sets the value of the concern threshold for total size of
+ all inflated trees.
+
+`repo.structure.concern.blob-inflated-size`::
+ Sets the value of the concern threshold for total size of
+ all inflated blobs.
+
+`repo.structure.concern.tag-inflated-size`::
+ Sets the value of the concern threshold for the total size
+ of all inflated tags.
+
+`repo.structure.concern.commit-largest`::
+ Sets the value of the concern threshold the size of the largest
+ commit.
+
+`repo.structure.concern.tree-largest`::
+ Sets the value of the concern threshold for the size of the
+ largest tree.
+
+`repo.structure.concern.blob-largest`::
+ Sets the value of the concern threshold for the size of the
+ largest blob.
+
+`repo.structure.concern.tag-largest`::
+ Sets the value of the concern threshold for the size of the
+ largest tag.
++
+All of the concern thresholds are integer values for the
+floor of the base-2 log of the threshold value. The default values
+of each threshold are set to heuristically determined values.
+
diff --git a/Documentation/git-repo.adoc b/Documentation/git-repo.adoc
index ed7d80c690..3c1045eb40 100644
--- a/Documentation/git-repo.adoc
+++ b/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 [--format=(table|lines|nul) | -z] [--[no-]concern]
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 [--format=(table|lines|nul) | -z] [--[no-]concern]`::
Retrieve statistics about the current repository structure. The
following kinds of information are reported:
+
@@ -88,6 +88,20 @@ supported:
quoted.
+
`-z` is an alias for `--format=nul`.
++
+To make it easier to know when one of the values is something that
+users should be concerned about, adding '--concern' will provide a
+level of concern to be added to the output. In 'table' mode, this will
+be a table column indicating the level of concern as a number of stars;
+in 'lines` or `nul' mode, a `concern_level` line will be added for each
+statistic with a numeric value.
++
+The level of corcern for each statistic is computed using the base_2 log of the
+statistic value. The value is considered concerning if it exceeds a heuristically
+chosen threshold value; the degree of concern is the difference between the
+base_2 log of the value, and the base_2 log of the corresponding threshold.
++
+The threshold values are configurable; see the configuration section below.
INFO KEYS
---------
@@ -141,6 +155,15 @@ using the `nul` format:
git repo info --format=nul layout.bare layout.shallow
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.adoc[]
+
+:git-repo: 1
+include::config/repo.adoc[]
+
+
SEE ALSO
--------
linkgit:git-rev-parse[1]
--
2.53.0