patchdocs: note that extensions.compatobjectformat is experimental

The compatibility object format is only implemented for loose objects, not packed objects, so anyone attempting to push or fetch data into a repository with this option will likely not see it work as expected. In addition, the underlying storage of loose object mapping is likely to change because the current format is inefficient and does not handle important mapping information such as that of submodules.

It would have been preferable to initially document that this was an experimental feature, but we did not do so. We hinted at the fact that this functionality is incomplete in the description, but did not say so explicitly. Let's do so now: indicate that this feature is experimental, incomplete, and subject to change.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
This was spurred by the fact that I saw Gitolite had added SHA-256
support and then that users were expecting extensions.compatobjectformat
to work, when it clearly does not (and, in fact, in some cases breaks
pushing into the repository).

I know that some people will not appreciate this feature being retroactively marked as experimental, but it is definitively broken for real-world use cases without the rest of my sha256-interop branch. Technically someone could always insert loose objects and then pack them, and because the old loose object mapping was present, the mapping would work, but, as mentioned, this would perform pathologically with even small repositories, so it's not a useful configuration.

 Documentation/config/extensions.adoc | 3 +++
 1 file changed, 3 insertions(+)

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

It is "experimental" in the sense that a developer who is interested in making the feature work end-to-end for the first time can use the code behind the flag to prepare loose objects to prepare what is to be transferred; it sounds more like this one is "not working yet" ...

... as the only end-user-perceivable purpose the compat format serves is to exchange data between two repositories that use different hash functions, no?

The word "experimental" to me implies that it at least lets you complete a minimum end-user journey of the feature end-to-end.

There are different degree of experimental in this project and we may want to do something about it, but in any case this is a welcome change in the right direction to steer those with mere curiosity away from hurting themselves.

    Note that the functionality hidden behind this extension is
    incomplete and the extension exists solely to allow us to
    continue developping it further.

might give them a stronger discouragement?

On 2025-08-25 at 17:25:57, Junio C Hamano wrote:

It works if you want to do `git rev-parse --output-object-format=sha1 <some-sha256-oid>` (or the reverse) and all of your objects entered the repository as loose objects. Otherwise, it isn't very useful.

It definitely does not currently let you exchange data between two repositories that use different hash functions unless you use my in-progress branch.

The eventual goal is to let people do something like `git rev-parse foobar^{sha1}` as well as interoperate with other repositories. Neither of those are currently in place.

I definitely don't think that's what it does. It has extremely limited useful functionality, pretty much entirely confined to rev-parse.

I'll re-roll with something like that in v2.

The compatibility object format is only implemented for loose objects, not packed objects, so anyone attempting to push or fetch data into a repository with this option will likely not see it work as expected. In addition, the underlying storage of loose object mapping is likely to change because the current format is inefficient and does not handle important mapping information such as that of submodules.

It would have been preferable to initially document that this was not yet ready for prime time, but we did not do so. We hinted at the fact that this functionality is incomplete in the description, but did not say so explicitly. Let's do so now: indicate that this feature is incomplete and subject to change and that the option is not designed to be used by end users.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/config/extensions.adoc | 4 ++++
 1 file changed, 4 insertions(+)

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

Much better. Let's further do "This option" -> "This extension", as all the others described in this document call themselves as such.

Thanks.

On 2025-08-25 at 22:46:26, Junio C Hamano wrote:

Great, I've just sent a v3 that does that.

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

As there are two of them, I'll use my local fixup! instead ;-)

The compatibility object format is only implemented for loose objects, not packed objects, so anyone attempting to push or fetch data into a repository with this option will likely not see it work as expected. In addition, the underlying storage of loose object mapping is likely to change because the current format is inefficient and does not handle important mapping information such as that of submodules.

It would have been preferable to initially document that this was not yet ready for prime time, but we did not do so. We hinted at the fact that this functionality is incomplete in the description, but did not say so explicitly. Let's do so now: indicate that this feature is incomplete and subject to change and that the option is not designed to be used by end users.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/config/extensions.adoc | 4 ++++
 1 file changed, 4 insertions(+)