What are the dos and don'ts of custom objects and refs?

Question

Let's say I want to write a small helper that allows to append some metadata to a repository in a way that can propagate to clones via refs. Simple example (a git-notes clone prototype that doesn't even attach the notes to any other git object):

hash=$(echo "Just a comment" | git hash-object -w --stdin)
git update-ref refs/comments/just $hash

i.e. I create a blob with hash hash and refer to that as refs/comments/just so git fsck --unreachable won't complain about it and git gc will never prune the object.

But that is of course a very simple example, in reality I'm interested in more complex features. And there, my question is, what can I "legally" do and what should I absolutely refrain from?

As an example, several posts on SE were about users having to recover from duplicate tree entries. So one "don't" is therefore "don't create a tree with duplicate entries". Another example is "do make sure your objects are reachable, so git prune won't remove them". What else?

Can I create a custom object type? Use "invalid" filemodes for blobs in trees? Where can I find an overview? Or should I check git-fsck's source manually to see what constitutes errors (and which ones are ignore-able)?

Calciferous

as an aside, rather than echo to a file, see git update-ref. – Facies

I see someone has voted to close this as "too broad", but I think you've pretty much answered it yourself: consult the git fsck source. :-) Note that it currently allows a few "historic mistakes", such as mode 664, and that it has grown additional tests over time, so you may wish to be very careful if you're doing something that "feels a bit off" but that git-fsck doesn't hate. As @Facies noted, use git update-ref to manipulate special refs. – Jamilla

@Facies I knew there must be a command for that, thanks :) – Calciferous

@Jamilla The trouble with consulting the source means I can't be certain this won't change in the future. Maybe there is a more API-ish document about this? I'm certainly not the first one wanting to do this, right? From what I read e.g. gerrit can also use refs for review, though I guess that really just sticks to blobs... – Calciferous

@TobiasKienzler there are some API docs, but nothing quite on that level. You definitely can't add new object types (Git wouldn't know what to do with them—if they're "leaf" types like blobs, one could argue that Git should not interpret them, but then you might as well just use "blob" anyway) and fsck will limit what you can do with trees (plus they're darn difficult to manipulate) so in the end you're back to git notes equivalents. – Jamilla

@Jamilla I was afraid you'd say that... But you're right, it's hard to imagine anything but blobs and trees necessary (and of course there's also the commit type, which is kind of a super-tree with "anonymous" parents, a blob-ish message and one tree linked). I sometimes have an idea and think "that would require some other object type" but after a while it actually turns out the existing type would do just fine... – Calciferous

Since I see you're still here, what specific difference is there between "notes that doesn't even attach the notes to any other git object" and just an ordinary sideband branch (with its own root)? Make your "mynotes" branch, check it out into a git worktree added tree wherever you want, and have your way with it. – Facies

@jthil tbh I don't remember my exact idea since it's been six years ago, but your suggestion sounds like it makes sense, thanks! – Calciferous