Kind 30618: Git Repository State Announcement

Overview

Kind 30618 provides a source of truth for the current state of branches and tags in a Git repository announced on Nostr. It allows repository maintainers to publish the current commit IDs of branches and tags, enabling clients to track repository state without directly accessing the Git server.

Specification

Property	Value
Kind Number	30618
Event Range	Parameterized Replaceable Event
Defined in	NIP-34

Content Format

The content field is typically empty for Git repository state announcements. All relevant information is contained in the event tags.

Schema

""

Tags

Tag Name	Description	Format	Required
d	Repository identifier	["d", "<repo-id>"]	Yes
refs/<heads|tags>/<branch-or-tag-name>	Branch or tag reference	["refs/<heads|tags>/<branch-or-tag-name>", "<commit-id>", "<shorthand-parent-commit-id>", "<shorthand-grandparent>", ...]	No
HEAD	Default branch pointer	["HEAD", "ref: refs/heads/<branch-name>"]	No

Client Behavior

Clients should:

• Use this event to determine the current state of branches and tags in a repository.
• Display the current state of the repository in a user-friendly manner.
• Track changes to repository state over time by monitoring updates to these events.
• If no refs tags are present, interpret this as the author no longer tracking repository state using this event.
• Recognize parent-child relationships among commits when the extended format of the refs tag is used.

Relay Behavior

Relays should:

• Store these events according to NIP-01 guidelines.
• Special handling is not required beyond standard event handling for parameterized replaceable events.

Use Cases

• Providing a source of truth for the state of branches and tags in a Git repository.
• Notifying followers about updates to repository branches without them needing access to the Git server.
• Tracking how many commits ahead a specific version is by using the extended refs tag format.
• Signaling that repository state tracking has been discontinued (when no refs tags are present).

Example

{
  "id": "d7397f556d9d0acade7b363dfd7d2050a6718a6eb5fb1bda583ebb4b2df07722",
  "pubkey": "32e1827635450ebb3c5a7d12c1f8e7b2b514439ac10a67eef3d9fd9c5c68e245",
  "created_at": 1677167950,
  "kind": 30618,
  "tags": [
    ["d", "nostr-protocol"],
    ["refs/heads/master", "a722f8a0ed2e5b43b6573eb11d7c30069d8e23ba"],
    ["refs/heads/develop", "e0a88c97b0f2a7cc9b0f3ef20fd5c9970ef40a5c", "a722f8a0", "9c04e22f"],
    ["refs/tags/v1.0.0", "9c04e22f6ad3d25e97be2cea782a6179ffff7e4a"],
    ["HEAD", "ref: refs/heads/master"]
  ],
  "content": "",
  "sig": "8f65886e1ea0a71e3e99d5ccd6af9e793cdce0eee7f8370a3eb26cc2c4fa70543492bda85a4664fb3b0bfb257945c7bafa97d77c15fd2fd9bf7a51bfbc59a254"
}

References

• NIP-34: Git Stuff
• Git Website

Related Kinds

• Kind 30617: Git Repository Announcement
• Kind 1617: Git Patch
• Kind 1621: Git Issue
• Kinds 1630-1633: Git Status Events (Open, Applied/Merged, Closed, Draft)

Notes

The absence of refs tags indicates that the author is no longer tracking repository state using this event. This approach enables the author to restart tracking state at a later time, unlike NIP-09 deletion requests.

The refs tag can be optionally extended to enable clients to identify how many commits ahead a reference is by including shorthand parent commit IDs in sequence.