[v3,0/4] document fsck error message ids

Message

Junio C Hamano Oct. 25, 2022, 10:42 p.m. UTC

"git fsck" reports various anomalies it finds in the form of message
tokens, like `badDate`, in its error message, and allows most of
them to be tweaked for their severity levels via configuration
varialbes, like `fsck.badDate`.  We however do not have them
centrally documented anywhere, other than the header file itself
(and the header file does not have explanation on what they mean).

This is John's work, with a bit of help from me.

 * Patches 1 and 2 remove fsck error message IDs from fsck.h that
   are not used in today's code.

 * In patch 3, "git fsck --help" gains a section that lists all the
   fsck error message ids with explanation.  "git config --help"
   gains a reference to the section.

 * While we worked on patch 3, we made many small mistakes (like
   spelling the tokens with incorrect camelCasing, or failing to
   list a few messages), which revealed the need of automated tool
   to catch them.  Patch 4 adds to "make check-docs" a mechanism to
   verify the documentation covers what is defined in fsck.h
   correctly.

Possible future directions that are left outside the scope of this
topic are:

 * "git config --help" may want to include the same list inline
   instead of having a reference to "git fsck --help".

 * Instead of the lint-docs support, we may want to auto-generate
   the documentation from fsck.h.


John Cai (2):
  fsck: remove the unused BAD_TAG_OBJECT
  fsck: document msg-id

Junio C Hamano (2):
  fsck: remove the unused MISSING_TREE_OBJECT
  Documentation: add lint-fsck-msgids

 Documentation/Makefile              |  11 ++
 Documentation/config/fsck.txt       |   4 +
 Documentation/fsck-msgids.txt       | 161 ++++++++++++++++++++++++++++
 Documentation/git-fsck.txt          |  12 +++
 Documentation/lint-fsck-msgids.perl |  70 ++++++++++++
 fsck.h                              |   8 +-
 6 files changed, 264 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/fsck-msgids.txt
 create mode 100755 Documentation/lint-fsck-msgids.perl