{"thread":{"id":"62386","subject":"[PATCH] doc: consolidate extensions in git-config documentation","startedAt":"2024-10-22T00:09:04Z","lastAt":"2024-10-22T17:33:58Z","messageCount":3,"participants":["Caleb White","Taylor Blau"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"505794","messageId":"20241021-cleanup-extension-docs-v1-1-ab02cece3132@pm.me","threadId":"62386","inReplyTo":null,"subject":"[PATCH] doc: consolidate extensions in git-config documentation","fromName":"Caleb White","fromEmail":"cdwhite3@pm.me","sentAt":"2024-10-22T00:08:49Z","receivedAt":"2024-10-22T00:09:04Z","isPatch":true,"sender":{"key":"cdwhite3@pm.me","avatar":"https://avatars.githubusercontent.com/u/4176520?v=4"},"body":"The `technical/repository-version.txt` document originally served as the\nmaster list for extensions, requiring that any new extensions be defined\nthere. However, the `config/extensions.txt` file was introduced later\nand has since become the de facto location for describing extensions,\nwith several extensions listed there but missing from\n`repository-version.txt`.\n\nThis consolidates all extension definitions into `config/extensions.txt`,\nmaking it the authoritative source for extensions. The references in\n`repository-version.txt` are updated to point to `config/extensions.txt`,\nand cross-references to related documentation such as\n`gitrepository-layout[5]` and `git-config[1]` are added.\n\nSuggested-by: Junio C Hamano <gitster@pobox.com>\nSigned-off-by: Caleb White <cdwhite3@pm.me>\n---\nThis patch was based on v2.47.0.\n---\n Documentation/config/core.txt                      |  2 +-\n Documentation/config/extensions.txt                | 73 ++++++++++++++++------\n Documentation/gitrepository-layout.txt             |  1 +\n .../technical/hash-function-transition.txt         |  4 +-\n Documentation/technical/partial-clone.txt          |  2 +-\n Documentation/technical/repository-version.txt     | 44 +------------\n 6 files changed, 62 insertions(+), 64 deletions(-)\n\ndiff --git a/Documentation/config/core.txt b/Documentation/config/core.txt\nindex 60ca9f2b6861063c0e78307edcbbd25a9104472f..8f6d8e77541261d67abac4f990f36ebb29b568c6 100644\n--- a/Documentation/config/core.txt\n+++ b/Documentation/config/core.txt\n@@ -366,7 +366,7 @@ default in a bare repository.\n \n core.repositoryFormatVersion::\n \tInternal variable identifying the repository format and layout\n-\tversion.\n+\tversion. See linkgit:gitrepository-layout[5].\n \n core.sharedRepository::\n \tWhen 'group' (or 'true'), the repository is made shareable between\ndiff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt\nindex f0a784447db09856639ec43b443681f13c17c966..5dc569d1c9c77c15e32441493289f9c9dd5e7f0b 100644\n--- a/Documentation/config/extensions.txt\n+++ b/Documentation/config/extensions.txt\n@@ -1,17 +1,13 @@\n-extensions.objectFormat::\n-\tSpecify the hash algorithm to use.  The acceptable values are `sha1` and\n-\t`sha256`.  If not specified, `sha1` is assumed.  It is an error to specify\n-\tthis key unless `core.repositoryFormatVersion` is 1.\n+extensions.*::\n+\tUnless otherwise stated, is an error to specify an extension if\n+\t`core.repositoryFormatVersion` is not `1`. See\n+\tlinkgit:gitrepository-layout[5].\n +\n-Note that this setting should only be set by linkgit:git-init[1] or\n-linkgit:git-clone[1].  Trying to change it after initialization will not\n-work and will produce hard-to-diagnose issues.\n-\n-extensions.compatObjectFormat::\n-\n+--\n+compatObjectFormat::\n \tSpecify a compatibility hash algorithm to use.  The acceptable values\n \tare `sha1` and `sha256`.  The value specified must be different from the\n-\tvalue of extensions.objectFormat.  This allows client level\n+\tvalue of `extensions.objectFormat`.  This allows client level\n \tinteroperability between git repositories whose objectFormat matches\n \tthis compatObjectFormat.  In particular when fully implemented the\n \tpushes and pulls from a repository in whose objectFormat matches\n@@ -19,18 +15,55 @@ extensions.compatObjectFormat::\n \tcompatObjectFormat in addition to oids encoded with objectFormat to\n \tlocally specify objects.\n \n-extensions.refStorage::\n+noop::\n+\tThis extension does not change git's behavior at all. It is useful only\n+\tfor testing format-1 compatibility.\n++\n+For historical reasons, this extension is respected regardless of the\n+`core.repositoryFormatVersion` setting.\n+\n+noop-v1::\n+\tThis extension does not change git's behavior at all. It is useful only\n+\tfor testing format-1 compatibility.\n+\n+objectFormat::\n+\tSpecify the hash algorithm to use.  The acceptable values are `sha1` and\n+\t`sha256`.  If not specified, `sha1` is assumed.\n++\n+Note that this setting should only be set by linkgit:git-init[1] or\n+linkgit:git-clone[1].  Trying to change it after initialization will not\n+work and will produce hard-to-diagnose issues.\n+\n+partialClone::\n+\tWhen enabled, indicates that the repo was created with a partial clone\n+\t(or later performed a partial fetch) and that the remote may have\n+\tomitted sending certain unwanted objects.  Such a remote is called a\n+\t\"promisor remote\" and it promises that all such omitted objects can\n+\tbe fetched from it in the future.\n++\n+The value of this key is the name of the promisor remote.\n++\n+For historical reasons, this extension is respected regardless of the\n+`core.repositoryFormatVersion` setting.\n+\n+preciousObjects::\n+\tIf enabled, indicates that objects in the repository MUST NOT be deleted\n+\t(e.g., by `git-prune` or `git repack -d`).\n++\n+For historical reasons, this extension is respected regardless of the\n+`core.repositoryFormatVersion` setting.\n+\n+refStorage::\n \tSpecify the ref storage format to use. The acceptable values are:\n +\n include::../ref-storage-format.txt[]\n-+\n-It is an error to specify this key unless `core.repositoryFormatVersion` is 1.\n+\n +\n Note that this setting should only be set by linkgit:git-init[1] or\n linkgit:git-clone[1]. Trying to change it after initialization will not\n work and will produce hard-to-diagnose issues.\n \n-extensions.worktreeConfig::\n+worktreeConfig::\n \tIf enabled, then worktrees will load config settings from the\n \t`$GIT_DIR/config.worktree` file in addition to the\n \t`$GIT_COMMON_DIR/config` file. Note that `$GIT_COMMON_DIR` and\n@@ -40,7 +73,7 @@ extensions.worktreeConfig::\n \t`config.worktree` file will override settings from any other\n \tconfig files.\n +\n-When enabling `extensions.worktreeConfig`, you must be careful to move\n+When enabling this extension, you must be careful to move\n certain values from the common config file to the main working tree's\n `config.worktree` file, if present:\n +\n@@ -48,15 +81,17 @@ certain values from the common config file to the main working tree's\n   `$GIT_COMMON_DIR/config.worktree`.\n * If `core.bare` is true, then it must be moved from `$GIT_COMMON_DIR/config`\n   to `$GIT_COMMON_DIR/config.worktree`.\n+\n +\n It may also be beneficial to adjust the locations of `core.sparseCheckout`\n and `core.sparseCheckoutCone` depending on your desire for customizable\n sparse-checkout settings for each worktree. By default, the `git\n-sparse-checkout` builtin enables `extensions.worktreeConfig`, assigns\n+sparse-checkout` builtin enables this extension, assigns\n these config values on a per-worktree basis, and uses the\n `$GIT_DIR/info/sparse-checkout` file to specify the sparsity for each\n worktree independently. See linkgit:git-sparse-checkout[1] for more\n details.\n +\n-For historical reasons, `extensions.worktreeConfig` is respected\n-regardless of the `core.repositoryFormatVersion` setting.\n+For historical reasons, this extension is respected regardless of the\n+`core.repositoryFormatVersion` setting.\n+--\ndiff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt\nindex 949cd8a31e9a9e896ccec63d5c7e2f23f740973a..fa8b51daf08775f3d666a910d9b00486627e02af 100644\n--- a/Documentation/gitrepository-layout.txt\n+++ b/Documentation/gitrepository-layout.txt\n@@ -298,6 +298,7 @@ SEE ALSO\n --------\n linkgit:git-init[1],\n linkgit:git-clone[1],\n+linkgit:git-config[1],\n linkgit:git-fetch[1],\n linkgit:git-pack-refs[1],\n linkgit:git-gc[1],\ndiff --git a/Documentation/technical/hash-function-transition.txt b/Documentation/technical/hash-function-transition.txt\nindex ed574810891cad1024658920e0fa8ac550231534..7102c7c8f5d66de5574de459a0e1136131a53004 100644\n--- a/Documentation/technical/hash-function-transition.txt\n+++ b/Documentation/technical/hash-function-transition.txt\n@@ -148,8 +148,8 @@ Detailed Design\n Repository format extension\n ~~~~~~~~~~~~~~~~~~~~~~~~~~~\n A SHA-256 repository uses repository format version `1` (see\n-Documentation/technical/repository-version.txt) with extensions\n-`objectFormat` and `compatObjectFormat`:\n+linkgit:gitrepository-layout[5]) with `extensions.objectFormat` and\n+`extensions.compatObjectFormat` (see linkgit:git-config[1]) set to:\n \n \t[core]\n \t\trepositoryFormatVersion = 1\ndiff --git a/Documentation/technical/partial-clone.txt b/Documentation/technical/partial-clone.txt\nindex cd948b00722cba5ae9f01b31f6a226f8d4497ea8..bf5ec5c82d9e0f2fedfec517a6a86d9973f4f312 100644\n--- a/Documentation/technical/partial-clone.txt\n+++ b/Documentation/technical/partial-clone.txt\n@@ -102,7 +102,7 @@ or commits that reference missing trees.\n - On the client a repository extension is added to the local config to\n   prevent older versions of git from failing mid-operation because of\n   missing objects that they cannot handle.\n-  See \"extensions.partialClone\" in Documentation/technical/repository-version.txt\"\n+  See `extensions.partialClone` in linkgit:git-config[1].\n \n \n Handling Missing Objects\ndiff --git a/Documentation/technical/repository-version.txt b/Documentation/technical/repository-version.txt\nindex 47281420fc4a0c901d60b2854a8f0a6e8f70587a..b9bb81a81f9ea16830290dfabd0839f1f05b1992 100644\n--- a/Documentation/technical/repository-version.txt\n+++ b/Documentation/technical/repository-version.txt\n@@ -65,44 +65,6 @@ Note that if no extensions are specified in the config file, then\n provides no benefit, and makes the repository incompatible with older\n implementations of git).\n \n-This document will serve as the master list for extensions. Any\n-implementation wishing to define a new extension should make a note of\n-it here, in order to claim the name.\n-\n-The defined extensions are:\n-\n-==== `noop`\n-\n-This extension does not change git's behavior at all. It is useful only\n-for testing format-1 compatibility.\n-\n-==== `preciousObjects`\n-\n-When the config key `extensions.preciousObjects` is set to `true`,\n-objects in the repository MUST NOT be deleted (e.g., by `git-prune` or\n-`git repack -d`).\n-\n-==== `partialClone`\n-\n-When the config key `extensions.partialClone` is set, it indicates\n-that the repo was created with a partial clone (or later performed\n-a partial fetch) and that the remote may have omitted sending\n-certain unwanted objects.  Such a remote is called a \"promisor remote\"\n-and it promises that all such omitted objects can be fetched from it\n-in the future.\n-\n-The value of this key is the name of the promisor remote.\n-\n-==== `worktreeConfig`\n-\n-If set, by default \"git config\" reads from both \"config\" and\n-\"config.worktree\" files from GIT_DIR in that order. In\n-multiple working directory mode, \"config\" file is shared while\n-\"config.worktree\" is per-working directory (i.e., it's in\n-GIT_COMMON_DIR/worktrees/<id>/config.worktree)\n-\n-==== `refStorage`\n-\n-Specifies the file format for the ref database. The valid values are\n-`files` (loose references with a packed-refs file) and `reftable` (see\n-Documentation/technical/reftable.txt).\n+The defined extensions are given in the `extensions.*` section of\n+linkgit:git-config[1]. Any implementation wishing to define a new\n+extension should make a note of it there, in order to claim the name.\n\n---\nbase-commit: 777489f9e09c8d0dd6b12f9d90de6376330577a2\nchange-id: 20241020-cleanup-extension-docs-f365868711bf\n\nBest regards,\n-- \nCaleb White <cdwhite3@pm.me>\n\n\n"},{"id":"505847","messageId":"ZxfdJs5+YbpHgpdv@nand.local","threadId":"62386","inReplyTo":"20241021-cleanup-extension-docs-v1-1-ab02cece3132@pm.me","subject":"Re: [PATCH] doc: consolidate extensions in git-config documentation","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-10-22T17:13:10Z","receivedAt":"2024-10-22T17:13:13Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Tue, Oct 22, 2024 at 12:08:49AM +0000, Caleb White wrote:\n> diff --git a/Documentation/config/extensions.txt b/Documentation/config/extensions.txt\n> index f0a784447db09856639ec43b443681f13c17c966..5dc569d1c9c77c15e32441493289f9c9dd5e7f0b 100644\n> --- a/Documentation/config/extensions.txt\n> +++ b/Documentation/config/extensions.txt\n> @@ -1,17 +1,13 @@\n> -extensions.objectFormat::\n> -\tSpecify the hash algorithm to use.  The acceptable values are `sha1` and\n> -\t`sha256`.  If not specified, `sha1` is assumed.  It is an error to specify\n> -\tthis key unless `core.repositoryFormatVersion` is 1.\n> +extensions.*::\n> +\tUnless otherwise stated, is an error to specify an extension if\n> +\t`core.repositoryFormatVersion` is not `1`. See\n> +\tlinkgit:gitrepository-layout[5].\n>  +\n> -Note that this setting should only be set by linkgit:git-init[1] or\n> -linkgit:git-clone[1].  Trying to change it after initialization will not\n> -work and will produce hard-to-diagnose issues.\n> -\n> -extensions.compatObjectFormat::\n> -\n> +--\n> +compatObjectFormat::\n\nShould this be `extensions.compatObjectFormat` instead of\n`compatObjectFormat`? I think the latter will produce awkward headings\nwhen these all get merged into git-config(1).\n\nOtherwise, looking good. Thanks for working on this!\n\nThanks,\nTaylor\n"},{"id":"505849","messageId":"D52IK8WN7D0S.2SGBXWAEE2CBZ@pm.me","threadId":"62386","inReplyTo":"ZxfdJs5+YbpHgpdv@nand.local","subject":"Re: [PATCH] doc: consolidate extensions in git-config documentation","fromName":"Caleb White","fromEmail":"cdwhite3@pm.me","sentAt":"2024-10-22T17:33:52Z","receivedAt":"2024-10-22T17:33:58Z","isPatch":true,"sender":{"key":"cdwhite3@pm.me","avatar":"https://avatars.githubusercontent.com/u/4176520?v=4"},"body":"On Tue Oct 22, 2024 at 12:13 PM CDT, Taylor Blau wrote:\n> On Tue, Oct 22, 2024 at 12:08:49AM +0000, Caleb White wrote:\n>> -Note that this setting should only be set by linkgit:git-init[1] or\n>> -linkgit:git-clone[1].  Trying to change it after initialization will not\n>> -work and will produce hard-to-diagnose issues.\n>> -\n>> -extensions.compatObjectFormat::\n>> -\n>> +--\n>> +compatObjectFormat::\n>\n> Should this be `extensions.compatObjectFormat` instead of\n> `compatObjectFormat`? I think the latter will produce awkward headings\n> when these all get merged into git-config(1).\n\nNo, I built the man pages and visually inspected the changes to ensure\nthey were formatted correctly. This is modeled after the `advice.*`\nconfig section which has the sub-sections listed as an indented block\nunder the main `advice` section. It looks like the following:\n\n    extensions.*\n        <description>\n\n        compatObjectFormat\n            <description>\n\n        <next extension>\n\nOne thing we might could do is bold the sub-sections, but the `advice.*`\nsection doesn't do that so I didn't do it here.\n\n> Otherwise, looking good. Thanks for working on this!\n\nSure thing!\n\nBest,\n\n"}]}