Merge 396beff41b into 2ace01cf1a

34.md

@@ -165,6 +165,81 @@ The most recent Status event (by `created_at` date) from either the issue/patch
 
 The Status of a patch-revision is to either that of the root-patch, or `1632` (_Closed_) if the root-patch's Status is `1631` (_Applied/Merged_) and the patch-revision isn't tagged in the `1631` (_Applied/Merged_) event.
 
+## Git Diffs
+
+Git Diff events (`kind: 1622`) represent changes between two commits within a Git repository, encapsulated as a unified diff. This event type is distinct from Git patches as it explicitly represents the state difference between two specific commits rather than modifications intended for direct application.
+
+Clients should render the event's `content` field as preformatted unified diff text (commonly displayed with diff highlighting).
+
+```jsonc
+{
+  "kind": 1622,
+  "content": "<git unified-diff content>",
+  "tags": [
+    // Reference to the repo's 30617 event if one exists 
+    ["a", "30617:<base-repo-owner-pubkey>:<base-repo-id>"],
+    // Explicit commit ID this diff represents (mandatory)
+    ["commit", "<current-commit-id>"],
+    // Parent commit ID from which the diff is generated (mandatory)
+    ["parent-commit", "<parent-commit-id>"],
+
+    // Explicit repository URL (optional if resolvable via 'a' tag, recommended for interoperability)
+    ["repo", "https://github.com/user/repo.git"],
+    // refs associated with the repository
+    ["refs/<heads|tags>/<branch-or-tag-name>","<commit-id>"]
+    // File path within the repository affected by this diff (optional but recommended if diff is single-file)
+    ["file", "<fully-qualified-filepath>"],
+    // Optional start and end lines in the diff context (recommended for precise referencing)
+    ["lines", "172", "196"],
+    // Optional description for context or explanation of changes
+    ["description", "Implements new diff handling in NIP-34"]
+  ]
+}
+```
+
+Clients rendering Git Diff events SHOULD:
+
+- Display the unified diff content with syntax highlighting for added/removed lines.
+- Provide options to view or open the diff context within external repository browsers or local Git clients.
+- Use commit and parent-commit identifiers for querying or fetching the exact commit state.
+- Clearly indicate repository, branch, and file context if provided.
+
+This detailed structure improves clarity, usability, and interoperability, providing clients with comprehensive context and ensuring precise referencing and rendering.
+
+## Permalinks
+
+Permalink events (`kind: 1623`) represent a permanent reference to specific lines within a file from a Git repository. They are intended to directly reference code or documentation precisely and immutably. Clients should render the event's `content` field as preformatted text (code blocks).
+
+```jsonc
+{
+  "kind": 1623,
+  "content": "<referenced code or text excerpt>",
+  "tags": [
+    // Reference to the repo's 30617 event if one exists 
+    ["a", "30617:<repo-owner-pubkey>:<repo-id>"],
+    // Explicit repository URL (optional if resolvable via 'a' tag, recommended for interoperability)
+    ["repo", "<repo.url>"],
+    // refs associated with the repository (mandatory)
+    ["refs/<heads|tags>/<branch-or-tag-name>","<commit-id>"]
+    // Specific commit identifier referencing the repository state (mandatory)
+    ["commit", "<commit-id>"],
+    // Path to the specific file in the repository (mandatory)
+    ["file", "<fully-qualified-filepath>"],
+
+    // Start and end lines referenced within the file (optional, otherwise the event refers to the complete file)
+    ["lines", "<start-line>", "<optional-end-line>"],
+    // Language identifier for syntax highlighting (optional but recommended)
+    ["l", "<language>"],
+    ["description", "<short-text-description>"]
+  ]
+}
+```
+
+Clients rendering permalink events SHOULD:
+
+- Fetch and display the exact lines from the referenced commit and file if the content is not explicitly included or for verification.
+- Display provided code/text using syntax highlighting according to the specified language tag (`l`).
+- Offer navigation or direct links to view the file within external repository browsers or clients.
 
 ## Possible things to be added later