[PATCH v3 0/5] repo: extend info path reporting and structure statistics

["eslam reda via GitGitGadget" <gitgitgadget@gmail.com>]

This series improves git repo info and git repo structure with a
================================================================

cleanly split commit history and explicit documentation/tests.

For git repo info, this series:

 * introduces explicit command context plumbing (instead of ad-hoc global
   reliance in this codepath),
 * adds category-key expansion (for example, requesting layout expands to
   layout.* keys),
 * adds path-oriented keys (path.*) that expose repository locations,
 * adds --path-format=(absolute|relative) to control path rendering.

For git repo structure, this series adds richer metrics:

 * maximum inflated object size (overall + per type),
 * maximum on-disk object size (overall + per type),
 * maximum commit parent count,
 * maximum tree entry count,
 * maximum blob path length and path depth,
 * maximum annotated tag chain depth,
 * aggregate keyvalue/nul totals (references.count, objects.count,
   objects.inflated_size, objects.disk_size).

Tests and documentation are updated accordingly.

----------------------------------------------------------------------------


Why this change
===============

The intent is to make git repo more script-friendly and more useful for
repository diagnostics:

 * repo info becomes easier to query programmatically (category keys,
   explicit path formatting).
 * repo structure becomes more actionable by exposing outlier-focused
   metrics (maxima), not only totals.
 * keyvalue/nul output now includes aggregate totals so scripts do not need
   to recompute them externally.

----------------------------------------------------------------------------


Commit structure (v2 rewrite)
=============================

This iteration rewrites history into smaller logical steps (no
“fix-on-fix”):

 1. repo: teach info context and category keys
 2. repo: add path keys to repo info
 3. repo: add --path-format for info path output
 4. repo: add structure max object size metrics
 5. repo: add structure topology and path-depth metrics
 6. repo: add aggregate structure totals to keyvalue output
 7. t1900: cover repo info path keys and path-format
 8. t1901: extend structure metric coverage and portability
 9. docs: describe repo info path keys and structure metrics

All commits are signed off using real-name identity.

----------------------------------------------------------------------------


Changes since v1
================

 * Rewrote series into smaller logical commits.
 * Folded fixes into proper history (no trailing fix-up patches).
 * Unified author/sign-off identity to real name.
 * Addressed portability concerns raised in review:
   * hash-algorithm-sensitive expectations are handled robustly,
   * BSD/macOS wc whitespace behavior is handled in tests.
 * Improved test robustness around keyvalue/nul expectations.
 * Expanded docs to explicitly describe new keys/metrics and behavior.
 * Revalidated in Docker with focused and full test runs.

----------------------------------------------------------------------------


Validation
==========

Focused:

 * t1900-repo.sh
 * GIT_TEST_DEFAULT_REF_FORMAT=reftable t/t1901-repo-structure.sh

Full:

 * make -C t -j4 test in clean Docker environment
 * Result: failed 0

----------------------------------------------------------------------------

Eslam reda ragheb (5):
  repo: teach info context and category keys
  repo: add path keys to repo info
  repo: add --path-format for info path output
  t1900: cover repo info path keys and path-format
  docs: describe repo info path keys

 Documentation/git-repo.adoc |  60 ++++++++-
 builtin/repo.c              | 244 +++++++++++++++++++++++++++++++++---
 t/t1900-repo.sh             | 196 +++++++++++++++++++++++++++++
 3 files changed, 480 insertions(+), 20 deletions(-)


base-commit: 7c02d39fc2ed2702223c7674f73150d9a7e61ba4
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-2208%2Feslam-reda-div%2Fgsoc-contribute-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-2208/eslam-reda-div/gsoc-contribute-v3
Pull-Request: https://github.com/git/git/pull/2208

Range-diff vs v2:

  1:  99c8058298 =  1:  e9ea572e52 repo: teach info context and category keys
  2:  6d5b9ff075 =  2:  348e361fe7 repo: add path keys to repo info
  3:  5c438d045b =  3:  93585ad079 repo: add --path-format for info path output
  4:  504d9cf7a0 <  -:  ---------- repo: add structure max object size metrics
  5:  4b502925c9 <  -:  ---------- repo: add structure topology and path-depth metrics
  6:  1751181950 <  -:  ---------- repo: add aggregate structure totals to keyvalue output
  7:  fd18f28db0 =  4:  6ea263fee9 t1900: cover repo info path keys and path-format
  8:  0525ed4cd9 <  -:  ---------- t1901: extend structure metric coverage and portability
  9:  f17c0f03e5 !  5:  a2a6768042 docs: describe repo info path keys and structure metrics
     @@ Metadata
      Author: Eslam reda ragheb <eslam.reda.div@gmail.com>
      
       ## Commit message ##
     -    docs: describe repo info path keys and structure metrics
     +    docs: describe repo info path keys
      
     -    Document the newly added repo info capabilities, including
     -    category keys and path-oriented key definitions.
     -
     -    Also describe --path-format behavior for path outputs.
     -
     -    Update git repo structure documentation to cover newly reported
     -    maxima and aggregate keyvalue/nul fields.
     -
     -    This keeps command behavior and output keys fully specified for
     -    users and scripts.
     +    Document repo info category keys, path.* keys, and
     +    --path-format behavior.
      
          Signed-off-by: Eslam reda ragheb <eslam.reda.div@gmail.com>
      
     @@ Documentation/git-repo.adoc: supported:
       `structure [--format=(table|keyvalue|nul) | -z]`::
       	Retrieve statistics about the current repository structure. The
       	following kinds of information are reported:
     -@@ Documentation/git-repo.adoc: supported:
     - * Reachable object counts categorized by type
     - * Total inflated size of reachable objects by type
     - * Total disk size of reachable objects by type
     -+* Largest inflated reachable object size by type
     -+* Largest disk size of a reachable object by type
     -+* Largest parent count among reachable commits
     -+* Largest entry count among reachable trees
     -+* Longest and deepest path among reachable blobs
     -+* Deepest annotated tag chain
     - +
     - The output format can be chosen through the flag `--format`. Three formats are
     - supported:
     -@@ Documentation/git-repo.adoc: supported:
     - `keyvalue`:::
     - 	Each line of output contains a key-value pair for a repository stat.
     - 	The '=' character is used to delimit between the key and the value.
     -+	Both aggregate metrics and per-type metrics are included.
     - 	Values containing "unusual" characters are quoted as explained for the
     - 	configuration variable `core.quotePath` (see linkgit:git-config[1]).
     - 
      @@ Documentation/git-repo.adoc: supported:
       
       INFO KEYS

-- 
gitgitgadget