[NIP-34] Include commit message in repository state announcements

[anhernsarsalor]

Summary

The current NIP-34 spec for repository state announcements (kind 30618) only tracks refs and commit IDs, but doesn't capture the commit message. This makes it harder for clients to display meaningful information about the latest changes without additional git operations.

Problem

When displaying repository state to users, clients currently need to:

1. Parse the repository state event to get the latest commit ID
2. Make a separate git operation to fetch the commit message
3. Handle cases where the git server might be unreachable

This creates unnecessary complexity and potential failure points. Users looking at a repository list or dashboard can't quickly see what the latest changes were about.

Proposed Solution

Add an optional commit-msg tag to the repository state announcement event:

{
  "kind": 30618,
  "content": "",
  "tags": [
    ["d", "<repo-id>"],
    ["refs/heads/master", "<commit-id>"],
    ["commit-msg", "refs/heads/master", "<commit-message>"],
    ["HEAD", "ref: refs/heads/master"]
  ]
}

Benefits

• Better UX: Clients can show "what's new" without extra network calls
• Offline capability: Repository browsers work even when git servers are down
• Reduced complexity: Fewer moving parts in client implementations
• Consistency: Keeps all repository state info in one place

Implementation Notes

• Should be optional to maintain backward compatibility
• Limit to first line of commit message to prevent event bloat
• Only include for HEAD and main development branches to avoid spam
• Clients should gracefully handle missing commit messages

Alternative Considered

We could put commit messages in the event content field, but using tags makes it easier for clients to selectively display this info and maintains the structured approach of the rest of the spec.

This feels like a small addition that would significantly improve the developer experience when browsing repositories through Nostr clients.

---

Note: Since git commit hashes are calculated from the entire commit object (including the commit message, author, timestamp, etc.), including the commit message in these events doesn't introduce any security concerns or break determinism. The commit ID already cryptographically commits to the message content, so we're just making that information more accessible without additional trust assumptions.

[anhernsarsalor]

no opinions on the matter? shall I push a pull request

[fiatjaf]

I would rather see a "commit" kind, so repositories can publish one event for every commit. This could be also useful for CI/CD services to react to updates.

But this isn't bad either.

Maybe having it on the content is better. And maybe it shouldn't be specifically the commit message, but rather "anything that acts as a description of the current state of the repository" (which by default will just be the commit message, I can't think of anything else, but I also don't see a use case for this commit message so what do I know).

[anhernsarsalor]

I would rather see a "commit" kind, so repositories can publish one event for every commit.

I don't see a reason, since we already have the repository state kind

but I also don't see a use case for this commit message so what do I know

Actually, I can give you a concrete use case for including commit messages in the event.

On animestr where I display posts whenever new commits are pushed to the frontend repo.

Currently, I can show that a commit happened, but having access to the commit message would make these posts much more informative for users. It would save me from having to implement a separate git client just to fetch that additional context - especially valuable during the early days of this project.

This seems like a common enough use case where people want to display commit activity with meaningful context, rather than just "a commit happened."

[fiatjaf]

This is true, we should do this (but it should be optional).

@DanConwayDev @dluvian