{"thread":{"id":"64020","subject":"[PATCH] docs: note that extensions.compatobjectformat is experimental","startedAt":"2025-08-23T22:06:05Z","lastAt":"2025-08-25T23:00:13Z","messageCount":8,"participants":["brian m. carlson","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"524801","messageId":"20250823220601.336079-1-sandals@crustytoothpaste.net","threadId":"64020","inReplyTo":null,"subject":"[PATCH] docs: note that extensions.compatobjectformat is experimental","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-08-23T22:06:01Z","receivedAt":"2025-08-23T22:06:05Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"The compatibility object format is only implemented for loose objects,\nnot packed objects, so anyone attempting to push or fetch data into a\nrepository with this option will likely not see it work as expected.  In\naddition, the underlying storage of loose object mapping is likely to\nchange because the current format is inefficient and does not handle\nimportant mapping information such as that of submodules.\n\nIt would have been preferable to initially document that this was an\nexperimental feature, but we did not do so.  We hinted at the fact that\nthis functionality is incomplete in the description, but did not say so\nexplicitly.  Let's do so now: indicate that this feature is\nexperimental, incomplete, and subject to change.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\nThis was spurred by the fact that I saw Gitolite had added SHA-256\nsupport and then that users were expecting extensions.compatobjectformat\nto work, when it clearly does not (and, in fact, in some cases breaks\npushing into the repository).\n\nI know that some people will not appreciate this feature being\nretroactively marked as experimental, but it is definitively broken for\nreal-world use cases without the rest of my sha256-interop branch.\nTechnically someone could always insert loose objects and then pack\nthem, and because the old loose object mapping was present, the mapping\nwould work, but, as mentioned, this would perform pathologically with\neven small repositories, so it's not a useful configuration.\n\n Documentation/config/extensions.adoc | 3 +++\n 1 file changed, 3 insertions(+)\n\ndiff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\nindex 9e2f321a6d..292e95ddae 100644\n--- a/Documentation/config/extensions.adoc\n+++ b/Documentation/config/extensions.adoc\n@@ -14,6 +14,9 @@ compatObjectFormat::\n \tcompatObjectFormat.  As well as being able to use oids encoded in\n \tcompatObjectFormat in addition to oids encoded with objectFormat to\n \tlocally specify objects.\n++\n+Note that the functionality enabled by this option is experimental, incomplete,\n+and subject to change.\n \n noop::\n \tThis extension does not change git's behavior at all. It is useful only\n"},{"id":"524875","messageId":"xmqqo6s3qpne.fsf@gitster.g","threadId":"64020","inReplyTo":"20250823220601.336079-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH] docs: note that extensions.compatobjectformat is experimental","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-25T17:25:57Z","receivedAt":"2025-08-25T17:26:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n\n> The compatibility object format is only implemented for loose objects,\n> not packed objects, so anyone attempting to push or fetch data into a\n> repository with this option will likely not see it work as expected.  In\n> addition, the underlying storage of loose object mapping is likely to\n> change because the current format is inefficient and does not handle\n> important mapping information such as that of submodules.\n\nIt is \"experimental\" in the sense that a developer who is interested\nin making the feature work end-to-end for the first time can use the\ncode behind the flag to prepare loose objects to prepare what is to\nbe transferred; it sounds more like this one is \"not working yet\" ...\n\n> diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\n> index 9e2f321a6d..292e95ddae 100644\n> --- a/Documentation/config/extensions.adoc\n> +++ b/Documentation/config/extensions.adoc\n> @@ -14,6 +14,9 @@ compatObjectFormat::\n>  \tcompatObjectFormat.  As well as being able to use oids encoded in\n>  \tcompatObjectFormat in addition to oids encoded with objectFormat to\n>  \tlocally specify objects.\n> ++\n> +Note that the functionality enabled by this option is experimental, incomplete,\n> +and subject to change.\n\n... as the only end-user-perceivable purpose the compat format\nserves is to exchange data between two repositories that use\ndifferent hash functions, no?\n\nThe word \"experimental\" to me implies that it at least lets you\ncomplete a minimum end-user journey of the feature end-to-end.\n\nThere are different degree of experimental in this project and we\nmay want to do something about it, but in any case this is a welcome\nchange in the right direction to steer those with mere curiosity\naway from hurting themselves.\n\n    Note that the functionality hidden behind this extension is\n    incomplete and the extension exists solely to allow us to\n    continue developping it further.\n\nmight give them a stronger discouragement?\n\n>  noop::\n>  \tThis extension does not change git's behavior at all. It is useful only\n"},{"id":"524894","messageId":"aKzU0IP8muy-j1TV@fruit.crustytoothpaste.net","threadId":"64020","inReplyTo":"xmqqo6s3qpne.fsf@gitster.g","subject":"Re: [PATCH] docs: note that extensions.compatobjectformat is experimental","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-08-25T21:25:36Z","receivedAt":"2025-08-25T21:25:44Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2025-08-25 at 17:25:57, Junio C Hamano wrote:\n> \"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n> \n> > The compatibility object format is only implemented for loose objects,\n> > not packed objects, so anyone attempting to push or fetch data into a\n> > repository with this option will likely not see it work as expected.  In\n> > addition, the underlying storage of loose object mapping is likely to\n> > change because the current format is inefficient and does not handle\n> > important mapping information such as that of submodules.\n> \n> It is \"experimental\" in the sense that a developer who is interested\n> in making the feature work end-to-end for the first time can use the\n> code behind the flag to prepare loose objects to prepare what is to\n> be transferred; it sounds more like this one is \"not working yet\" ...\n> \n> > diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\n> > index 9e2f321a6d..292e95ddae 100644\n> > --- a/Documentation/config/extensions.adoc\n> > +++ b/Documentation/config/extensions.adoc\n> > @@ -14,6 +14,9 @@ compatObjectFormat::\n> >  \tcompatObjectFormat.  As well as being able to use oids encoded in\n> >  \tcompatObjectFormat in addition to oids encoded with objectFormat to\n> >  \tlocally specify objects.\n> > ++\n> > +Note that the functionality enabled by this option is experimental, incomplete,\n> > +and subject to change.\n> \n> ... as the only end-user-perceivable purpose the compat format\n> serves is to exchange data between two repositories that use\n> different hash functions, no?\n\nIt works if you want to do `git rev-parse --output-object-format=sha1\n<some-sha256-oid>` (or the reverse) and all of your objects entered the\nrepository as loose objects.  Otherwise, it isn't very useful.\n\nIt definitely does not currently let you exchange data between two\nrepositories that use different hash functions unless you use my\nin-progress branch.\n\nThe eventual goal is to let people do something like `git rev-parse\nfoobar^{sha1}` as well as interoperate with other repositories.  Neither\nof those are currently in place.\n\n> The word \"experimental\" to me implies that it at least lets you\n> complete a minimum end-user journey of the feature end-to-end.\n\nI definitely don't think that's what it does.  It has extremely limited\nuseful functionality, pretty much entirely confined to rev-parse.\n\n> There are different degree of experimental in this project and we\n> may want to do something about it, but in any case this is a welcome\n> change in the right direction to steer those with mere curiosity\n> away from hurting themselves.\n> \n>     Note that the functionality hidden behind this extension is\n>     incomplete and the extension exists solely to allow us to\n>     continue developping it further.\n> \n> might give them a stronger discouragement?\n\nI'll re-roll with something like that in v2.\n-- \nbrian m. carlson (they/them)\nToronto, Ontario, CA\n"},{"id":"524897","messageId":"20250825221101.611876-1-sandals@crustytoothpaste.net","threadId":"64020","inReplyTo":"20250823220601.336079-1-sandals@crustytoothpaste.net","subject":"[PATCH v2] docs: note that extensions.compatobjectformat is incomplete","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-08-25T22:11:01Z","receivedAt":"2025-08-25T22:11:08Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"The compatibility object format is only implemented for loose objects,\nnot packed objects, so anyone attempting to push or fetch data into a\nrepository with this option will likely not see it work as expected.  In\naddition, the underlying storage of loose object mapping is likely to\nchange because the current format is inefficient and does not handle\nimportant mapping information such as that of submodules.\n\nIt would have been preferable to initially document that this was not\nyet ready for prime time, but we did not do so.  We hinted at the fact\nthat this functionality is incomplete in the description, but did not\nsay so explicitly.  Let's do so now: indicate that this feature is\nincomplete and subject to change and that the option is not designed to\nbe used by end users.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/config/extensions.adoc | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\nindex 9e2f321a6d..df448da813 100644\n--- a/Documentation/config/extensions.adoc\n+++ b/Documentation/config/extensions.adoc\n@@ -14,6 +14,10 @@ compatObjectFormat::\n \tcompatObjectFormat.  As well as being able to use oids encoded in\n \tcompatObjectFormat in addition to oids encoded with objectFormat to\n \tlocally specify objects.\n++\n+Note that the functionality enabled by this option is incomplete and subject to\n+change.  This option currently exists only to allow development and testing of\n+the underlying feature and is not designed to be enabled by end users.\n \n noop::\n \tThis extension does not change git's behavior at all. It is useful only\n"},{"id":"524898","messageId":"xmqqms7nnhod.fsf@gitster.g","threadId":"64020","inReplyTo":"20250825221101.611876-1-sandals@crustytoothpaste.net","subject":"Re: [PATCH v2] docs: note that extensions.compatobjectformat is incomplete","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-25T22:46:26Z","receivedAt":"2025-08-25T22:46:29Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n\n> diff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\n> index 9e2f321a6d..df448da813 100644\n> --- a/Documentation/config/extensions.adoc\n> +++ b/Documentation/config/extensions.adoc\n> @@ -14,6 +14,10 @@ compatObjectFormat::\n>  \tcompatObjectFormat.  As well as being able to use oids encoded in\n>  \tcompatObjectFormat in addition to oids encoded with objectFormat to\n>  \tlocally specify objects.\n> ++\n> +Note that the functionality enabled by this option is incomplete and subject to\n> +change.  This option currently exists only to allow development and testing of\n> +the underlying feature and is not designed to be enabled by end users.\n\nMuch better.  Let's further do \"This option\" -> \"This extension\", as\nall the others described in this document call themselves as such.\n\nThanks.\n"},{"id":"524899","messageId":"20250825225018.625943-1-sandals@crustytoothpaste.net","threadId":"64020","inReplyTo":"20250823220601.336079-1-sandals@crustytoothpaste.net","subject":"[PATCH v3] docs: note that extensions.compatobjectformat is incomplete","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-08-25T22:50:18Z","receivedAt":"2025-08-25T22:50:22Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"The compatibility object format is only implemented for loose objects,\nnot packed objects, so anyone attempting to push or fetch data into a\nrepository with this option will likely not see it work as expected.  In\naddition, the underlying storage of loose object mapping is likely to\nchange because the current format is inefficient and does not handle\nimportant mapping information such as that of submodules.\n\nIt would have been preferable to initially document that this was not\nyet ready for prime time, but we did not do so.  We hinted at the fact\nthat this functionality is incomplete in the description, but did not\nsay so explicitly.  Let's do so now: indicate that this feature is\nincomplete and subject to change and that the option is not designed to\nbe used by end users.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/config/extensions.adoc | 4 ++++\n 1 file changed, 4 insertions(+)\n\ndiff --git a/Documentation/config/extensions.adoc b/Documentation/config/extensions.adoc\nindex 9e2f321a6d..9d50a3501e 100644\n--- a/Documentation/config/extensions.adoc\n+++ b/Documentation/config/extensions.adoc\n@@ -14,6 +14,10 @@ compatObjectFormat::\n \tcompatObjectFormat.  As well as being able to use oids encoded in\n \tcompatObjectFormat in addition to oids encoded with objectFormat to\n \tlocally specify objects.\n++\n+Note that the functionality enabled by this option is incomplete and subject to\n+change.  This extension currently exists only to allow development and testing of\n+the underlying feature and is not designed to be enabled by end users.\n \n noop::\n \tThis extension does not change git's behavior at all. It is useful only\n"},{"id":"524900","messageId":"aKzoyFbdohhpiEzK@fruit.crustytoothpaste.net","threadId":"64020","inReplyTo":"xmqqms7nnhod.fsf@gitster.g","subject":"Re: [PATCH v2] docs: note that extensions.compatobjectformat is incomplete","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2025-08-25T22:50:48Z","receivedAt":"2025-08-25T22:50:50Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2025-08-25 at 22:46:26, Junio C Hamano wrote:\n> Much better.  Let's further do \"This option\" -> \"This extension\", as\n> all the others described in this document call themselves as such.\n\nGreat, I've just sent a v3 that does that.\n-- \nbrian m. carlson (they/them)\nToronto, Ontario, CA\n"},{"id":"524902","messageId":"xmqqcy8jnh1g.fsf@gitster.g","threadId":"64020","inReplyTo":"aKzoyFbdohhpiEzK@fruit.crustytoothpaste.net","subject":"Re: [PATCH v2] docs: note that extensions.compatobjectformat is incomplete","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-08-25T23:00:11Z","receivedAt":"2025-08-25T23:00:13Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" <sandals@crustytoothpaste.net> writes:\n\n> On 2025-08-25 at 22:46:26, Junio C Hamano wrote:\n>> Much better.  Let's further do \"This option\" -> \"This extension\", as\n>> all the others described in this document call themselves as such.\n>\n> Great, I've just sent a v3 that does that.\n\nAs there are two of them, I'll use my local fixup! instead ;-)\n"}]}