From b2558abdc471758ae8b30c1198e833a7a1c6616c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Fri, 27 Jul 2018 14:37:13 +0000 Subject: [PATCH] config doc: unify the description of fsck.* and receive.fsck.* MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The documentation for the fsck. and receive.fsck. variables was mostly duplicated in two places, with fsck. making no mention of the corresponding receive.fsck., and the same for fsck.skipList. I spent quite a lot of time today wondering why setting the fsck. variant wasn't working to clone a legacy repository (not that that would have worked anyway, but a subsequent patch implements fetch.fsck.). Rectify this situation by describing the feature in general terms under the fsck.* documentation, and make the receive.fsck.* documentation refer to those variables instead. This documentation was initially added in 2becf00ff7 ("fsck: support demoting errors to warnings", 2015-06-22) and 4b55b9b479 ("fsck: document the new receive.fsck. options", 2015-06-22). Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/config.txt | 58 +++++++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 25 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 6b99cf8d71..8d08250a5b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -1595,15 +1595,30 @@ filter..smudge:: linkgit:gitattributes[5] for details. fsck.:: - Allows overriding the message type (error, warn or ignore) of a - specific message ID such as `missingEmail`. + During fsck git may find issues with legacy data which + wouldn't be generated by current versions of git, and which + wouldn't be sent over the wire if `transfer.fsckObjects` was + set. This feature is intended to support working with legacy + repositories containing such data. + -For convenience, fsck prefixes the error/warning with the message ID, -e.g. "missingEmail: invalid author/committer line - missing email" means -that setting `fsck.missingEmail = ignore` will hide that issue. +Setting `fsck.` will be picked up by linkgit:git-fsck[1], but +to accept pushes of such data set `receive.fsck.` instead. + -This feature is intended to support working with legacy repositories -which cannot be repaired without disruptive changes. +The rest of the documentation discusses `fsck.*` for brevity, but the +same applies for the corresponding `receive.fsck.*` variables. ++ +When `fsck.` is set, errors can be switched to warnings and +vice versa by configuring the `fsck.` setting where the +`` is the fsck message ID and the value is one of `error`, +`warn` or `ignore`. For convenience, fsck prefixes the error/warning +with the message ID, e.g. "missingEmail: invalid author/committer line +- missing email" means that setting `fsck.missingEmail = ignore` will +hide that issue. ++ +In general, it is better to enumerate existing objects with problems +with `fsck.skipList`, instead of listing the kind of breakages these +problematic objects share to be ignored, as doing the latter will +allow new instances of the same breakages go unnoticed. fsck.skipList:: The path to a sorted list of object names (i.e. one SHA-1 per @@ -1612,6 +1627,9 @@ fsck.skipList:: should be accepted despite early commits containing errors that can be safely ignored such as invalid committer email addresses. Note: corrupt objects cannot be skipped with this setting. ++ +Like `fsck.` this variable has a corresponding +`receive.fsck.skipList` variant. gc.aggressiveDepth:: The depth parameter used in the delta compression @@ -2893,26 +2911,16 @@ receive.fsckObjects:: `transfer.fsckObjects` is used instead. receive.fsck.:: - When `receive.fsckObjects` is set to true, errors can be switched - to warnings and vice versa by configuring the `receive.fsck.` - setting where the `` is the fsck message ID and the value - is one of `error`, `warn` or `ignore`. For convenience, fsck prefixes - the error/warning with the message ID, e.g. "missingEmail: invalid - author/committer line - missing email" means that setting - `receive.fsck.missingEmail = ignore` will hide that issue. -+ -This feature is intended to support working with legacy repositories -which would not pass pushing when `receive.fsckObjects = true`, allowing -the host to accept repositories with certain known issues but still catch -other issues. + Acts like `fsck.`, but is used by + linkgit:git-receive-pack[1] instead of + linkgit:git-fsck[1]. See the `fsck.` documentation for + details. receive.fsck.skipList:: - The path to a sorted list of object names (i.e. one SHA-1 per - line) that are known to be broken in a non-fatal way and should - be ignored. This feature is useful when an established project - should be accepted despite early commits containing errors that - can be safely ignored such as invalid committer email addresses. - Note: corrupt objects cannot be skipped with this setting. + Acts like `fsck.skipList`, but is used by + linkgit:git-receive-pack[1] instead of + linkgit:git-fsck[1]. See the `fsck.skipList` documentation for + details. receive.keepAlive:: After receiving the pack from the client, `receive-pack` may